Principles of Developer Education

Fourteen principles for effective developer education.

1. Writing
2. Structure vs. Chaos
3. Sequencing vs. Complexity
4. Exceptions vs. Simplicity
5. Terminology
6. Time
7. Tangents
8. Product problems
9. Imagination
10. Distribution
11. Impact > Vibes
12. Automation
13. Agents as first-class users
14. Agentic Education

It starts with writing

It doesn’t matter what you’re creating (documentation, blog post, workshop, tutorial, video script, etc), it’ll likely start with writing. Luckily, technical writing has specific rules that can be learned. Active vs passive voice, this vs. this, etc. Iykyk.

The more you write, the more you’ll see these rules being applied (or broken) in the wild, and the better your “writing eye” will become at spotting and fixing them.

But it’s not about the act of writing itself, it’s about learning how to communicate complex topics well. As it turns out, technical writing is a shortcut to becoming a better communicator.

Learn the principles of technical writing with the free Google Technical Writing courses.

Organize chaos

The educator’s main job is to take disorganized information and give it structure.

This includes taking raw materials that are difficult to parse (source code, RFCs, changelogs, GitHub discussion, engineer-brain slop), and curating it into a structured format that is easy to understand and use.

This process is painful. Not many people can organize chaos well. It’s a skill that takes time to develop. So, if you are new to teching, focus on deciding what to include, what to omit, and how to sequence the content. This is the foundation everything else builds on.

Once you have nailed your process, you can codify it into skills for agents.

Progressive disclosure of complexity

Building on the above, sequencing matters.

Don’t front-load every edge case, caveat, and configuration option. Let people build a mental model first, then layer in complexity.

This applies to any content you’re creating (docs, tutorials, videos, etc). The first example should be the simplest thing that works. The second should introduce one new concept. Resist the urge to show everything you know upfront.

Exceptions are the death of simplicity

Have you written an API reference where half of the documentation was a list of exceptions? I have.

Exceptions are the death of simplicity. If an API or feature has too many exceptions, it’s a product problem. Not an education problem.

As educators, you need to build relationships with the product and engineering teams, give feedback, understand the tradeoffs of their decisions. Then iterate on the feature, and choose how much to expose to the user, together.

Nail your terminology

When explaining things, don’t slingshot terms at the learner.

Every undefined term you throw at the user is another piece of context they need to juggle in their head. This doesn’t mean dumbing things down and risk losing accuracy. It means being precise about when and how you introduce new language.

Don’t be afraid to invent new industry terms, but always anchor them to fundamentals. For example, early on, the React Server Component Payload was called Flight Data. Would your developers know what Flight Data meant? Probably not. Payload is a lot more intuitive.

Respect your audience's time

Every paragraph, every sentence, every word must earn its place.

Developers are busy and impatient. They’ll give you a few seconds to prove you’re worth their attention. Short beats long, every time. If it can be said in fewer words, do it.

This doesn’t mean being dry to the point of confusion. It means no filler, no preambles, no tangents. Get to the point.

Avoid tangents

Tangents are off-shoot ideas that add color and context. Much like new terms, tangents create cognetive overload.

You avoid tangents by targeting the right audience. If your audience is beginners, you start with the fundamentals before diving into the topic, that way you avoid tangents while teaching the topics. If your audience is advanced, you can afford to be more technical, but you should always have a glossary or reference to link to.

Most education problems are product problems

There are problems education alone can’t solve. These are product problems. If your product is broken, your education will be too.

As an educator, your job is to use the product, recognize where it’s broken or complex, and help the product and engineering teams fix it. That means, deciding when not to teach something because it’ll only highlight the problem more.

I learned this lesson the hard way with Next.js caching. Iykyk.

Expand the imagination

Your job as an educator is to help developers understand how to use the product in the real world. Or as I like to say, expand the imagination. Think about your users, what are they building? What are they struggling with? What would they be excited about?

From there, you can use education to enable them.

If you are scratching your head trying to figure out how to use the product you’re teaching, it’s a product problem. Not an education problem. Go back to your product team and brainstorm use cases and user journeys.

Meet developers where they are

Ten years ago, reaching developers meant conference talks. Five years ago, it was YouTube, X, and online communities. Today, agents are choosing tools, scaffolding projects, and writing code - increasingly without a human in the loop.

These distribution channels don’t go away. But their relative impact changes. Developer Education needs to evolve to meet developers where they are.

Impact over vibes

There are 100 things you can be creating content on. But only a few that will make a long-term impact. Education initiatives should be prioritized based on their impact, not vibes.

To measure impact, you’ll need to define your metrics. You can look at vanity metrics, but at the end of the day, you need to tie it back to business outcomes.

The 3 metrics I look at are:

1. Activation: MoM product growth
2. Engagement: how engaged are users with the content?
3. Reach: what distribution channels will reach the most developers?

Automate the grunt work

Content maintenance is a pain. AI can help. The key is to have “human-in-loop” workflows. Here are a few ideas:

• Community monitoring agents that listen to community forums and flag when you should be involved in conversations, or when there are content opportunity gaps.
• Product monitoring agents that listen for API changes and flag when docs drift from the source of truth. These agents can then open PRs for humans to review and merge.
• Skills for every content artifact, with style guidelines, that can be used by humans to create new content for launches.

Agents as first-class students

When you think about the relative impact of distribution channels, and how agents now add an exponential factor to the equation, it’s clear that the future of Developer Education treats agents as first-class students. This means creating agent-first content, that is, structured source of truth that get discovered by agents.

While agent content can be dry and boring. Human education will increasingly be about driving awareness and building connections.

llms.txt, skills, and embedding documentation are a few examples of how content is now being targeted at agents.

Agentic education is coming

When I think about the future of Developer Education, I get excited because AI can be a tool not only for teaching humans, but also for teaching agents how to teach humans.

To be good teachers, agents need good guardrails. And more and more, our job will be less about creating content, but “teaching the teacher”. Creating guardrails that teach agents how to deliver effective education.

These principles are work in progress, and will likely change with the industry. Last updated: 22nd February 2026.