Writing Good Documentation

Writing documentation is tough, knowing what your target audience will need to be told without writing so much they won’t bother reading it isn’t easy.

Documentation writing is much like teaching  – you need a level of patience and empathy.

Patience to spend the time to understand the needs of your learners (whether they’re 11 year olds learning to code, developers learning to use your software or the end user of your product) and to spend the time and effort writing it, checking it and updating it.

Empathy to be able to put yourselves in their shoes and understand what they want and need, and how they would find it best to consume it.

Types of Documentation

Documentation tends to take two forms:

  • Inline documentation – such as labels on forms or those little question marks you can click for more details or comments in code.
  • External documentation – where you have to know where to go to look it up. Ideally the inline documentation is brief and links to a more detailed explanation in the external documentation.

Bad Documentation

A common mistake new developers make when writing code is to write comments (because they’ve been told they must write lots) which just say what the code already says. For example:

// Open the file
$file = open_file("some_file")

The same is often done in user interfaces, this classic example from the otherwise excellent WooCommerces Bookings extension shows the developers writing the easy documentation, but leaving the more complicated bits until later – and eventually shipping without it.

Here they’ve added an explanation to the already intuitive boolean field labelled “Bookable” but made no effort to exaplin the could-be-anything field “First block starts at…”


Good Documentation

Good documentation:

  • is consistent – whatever you’re looking up is in the same format as other similar things
  • has examples – an example is the equivalent of a picture in the expression “A picture is worth 1,000 words”
  • is open to contributions – If I find something lacking in some documentation I’m still going to figure out how to solve the problem, to allow me to feed that back into the documentation for future users is invaluable.
  • has a “see also” or “related” section, so if the bit you’re reading about isn’t quite right you can explore to the correct place.

I think that Stripe, Apache and PHP all have excellent external documentations. PHP’s default php.ini is a good example of inline documentation.

If you have more opinions, or wish to praise or insult documentations you can comment below!