Writing good technical documentation 📝

How can you write technical documentation that is clear, informative, and even fun?¹

Who are you writing for? #

I find it helpful to think about what you want to achieve by writing the documentation. Who is it for? Are you writing for a beginner or an expert, an external user or your team mates? What do you want them to understand? What do you expect the readers to know in advance? Then think about what you need to explain.

Try to put yourself in the shoes of the reader. If they knew only what you wrote, would it make sense?

Don’t try to be too clever. You’re trying to help someone understand something, not proving how smart you are. (Remember, feeling smart is a warning sign.) Use simple language. Avoid technical jargon. Prefer active voice over passive.

On the other hand, don’t over-simplify the content either. If an expert cannot understand your simplified description, it is too simple.

Help the reader build a mental model #

The most helpful thing you can do as a technical writer is to give the reader a good mental model of the subject. A model that helps the reader make sense of everything, and gives them a framework to which they can attach the things they learn.

For example, to understand HTTP it is vital to understand the request-response nature. That makes it easier to understand why you need cookies, sessions, or tokens to persist state.

Does the documentation compile? #

You want your documentation to make sense to the reader.

An important aspect is to consider the order in which concepts are introduced. Identify the core abstractions first, then explain dependencies. If you are teaching someone Java, you likely want to explain integers and strings before you start teaching generics.

Focus on what the natural progression would be for a human. What concepts are helpful to know about before learning about other concepts? How can you connect the documentation to prior knowledge?

You should also make sure to use the same term each time for the same concept. And of course, it should be correct!

I like to ask myself “does the documentation compile” from a reading perspective? I think of it as a compilation error if the documentation:

• uses a term that has not been established,
• uses different terms for the same concept, or
• uses terms in a way that is not technically correct.

Does the documentation need refactoring? #

I like the idea of a “shitty first draft”²! Just get something down on paper. It is always easier to critique/refine something than starting with a blank page. So just write something and worry about improving it later.

With that first draft in place, it is time for some serious refactoring. Use “refactorings” such as extract paragraph, explain concept, or introduce heading. Keep related parts of the documentation on the same level of abstraction. Ask yourself if each paragraph is conceptually coherent. Does one paragraph or section naturally lead to the next?

Aim to make the documentation structure clear and easy to follow. For larger documentation sites, consider using a system such as Diátaxis to make the structure clear.

Does the document pass tests? #

Every now and then, step back and take a look at the documentation. Are you achieving what you set out to do?

It can be very helpful to ask a colleague or friend to review your documentation. Ask them what parts were hard to understand, or what areas need to be explained further. This feedback loop can improve your writing a lot.

Feel free to use AI as a help to review and critique your writing if you like.

Add a bit of life #

You are allowed to write technical documentation that is actually fun. 😊 It doesn’t need to be a standup routine, but we don’t have to put on our most serious face just because we’re writing documentation.

Does this documentation look fun? A lot of technical documentation can have that “wall of text” vibe. Try to avoid that by varying the appearance—use lists, code blocks, illustrations, graphs and similar to break up monotonous text.

For example, I think Lin Clark’s A cartoon intro to WebAssembly series hits a nice mix of technical depth and approachability.

Writing takes effort but is rewarding #

Good technical documentation, like software, requires effort. But writing documentation can be very rewarding.

You not only help others understand the topic, but often deepen your own understanding. Remember, if you can’t explain it, you don’t understand it.

Resist the urge to use AI to write documentation. If you can auto-generate documentation, then anyone can. Documentation worth keeping is usually the kind that can’t be generated.

With a bit of practice, you can create technical documentation that is both helpful and fun to read. Use this checklist as a guide.

• Who are you writing for?
• Is the mental model clear?
• Does the documentation “compile”?
• Is the structure clear and easy to follow?
• Can someone else understand it?
• Is it engaging?