How I write documentation

I write a lot of documentation and technical documents, for my team and my course students. A lot of it aims to teach, and some of it is traditional technical project documentation.

Here are a few things I’ve learned along the way.

  1. Put yourself in the shoes of your reader.
  2. What outcome does the reader expect?
  3. What questions does your reader have?
  4. Always be selling.

Put yourself in the shoes of your reader

My father used to complain that even beginner programming books might explain things simply, but you couldn’t escape the fact that the author was much more experienced than their audience.

You could see it by the unexplained acronyms, or the implied assumptions of knowledge.

Every author strives to avoid that, but there are a few things you can do to force yourself to be in touch with your audience:

  • Might sound obvious, but first simply pause and think for a moment who is going to be reading your writing.
  • Immerse yourself for a while (a few hours, or a few days) in the sort of code and systems that your reader uses.
  • As you write your drafts, ask an LLM for what questions might a reader have. This works particularly well if you give the LLM information about who your reader is.

It especially helps if you put yourself in the shoes of a specific person. You can think concretely about what they know and don’t know, and by imagining yourself speaking or explaining things to them, your writing will flow more easily.

The outcome of the document

Part of putting yourself in the shoes of your reader means thinking about what they want to get out of what you’re writing.

Are they learning? Staying “in the loop”? Buying something?

Tailoring your writing to the right outcome is important and will help you avoid faff.

Together, putting yourself in the shoes of the reader and thinking of the outcome of the document will help you see how the writing for these differs:

  • An internal codebase documentation.
  • A public e-book for new users to learn your library.

Questions: the 5 (or more) whys

The first two are (relatively) obvious, so now we come to something that has always served me well, but I don’t see used often.

”The 5 whys” is a problem-solving technique for getting to the root cause of a situation. The idea is that when you encounter a problem, you ask why it happened, and you keep asking that until you reach a root cause.

I’m not going to tell you that it’s a good technique generally, but it does work well for writing.

It helps write for your audience, and also it simply helps you write more efficiently, period!

Usually my drafts begin with one or a series of questions that my audience may have about the topic I’m writing about. Then each question becomes a top-level heading, and I come up with more questions related to each.

If you struggle to come up with questions, then just stick to one level deep. As you write, you’ll rely on assumed knowledge or mention concepts, and that’s where more potential questions will start to appear.

For example, let’s say you want to write something like this:

The easiest way to store data in your database is to use UTC timestamps.

You can put your questioning hat on, and come up with one level deep of questions:

  • What is UTC?
  • What is a timestamp?

This is assuming the audience will know what “data” and “database” is.

But then you can go another level deep:

  • What is a timezone?
  • How can you convert between timezones?
  • How do you store timezone information in a timestamp?
  • What happens with DST?
  • What is DST?

The list can go on, and it’s always up to you where it ends. You can’t explain every single thing to every single person, so try to put yourself in the shoes of your reader.

Always be selling

Most people don’t want to read what you write.

Sorry!

We’re in an era where attention spans are at an all-time low, and reading anything at all is already a huge commitment.

Your writing must give your readers more than the effort takes from them, so here are some ideas:

  • Focus your writing on one single idea.
  • Make your document structure straightforward.
  • Write simply and concisely. Use more full stops than commas.
  • Use diagrams, code blocks, or even images before the long, technical explanations.
  • Use more simple English with Saxon words that are shorter and clearer. But write rhythmically and intersperse Latin words too when you want to bring attention to a point.
  • If it’s possible, try to connect with your reader and write personally as opposed to facelessly.

Writer David Perell has an in-depth guide on writing online that I recommend.

Technical aspects, continuation

As well as the “how to write” aspect, there are also many technical aspects to writing documentation: apps, tools, libraries, and even languages.

I’ll leave that for another article!

Thank you for reading. Keep writing!

— Jose