Characteristics of Good Documentation

Jaken Herman
Mar 10, 2018 · 3 min read

As a developer, reading documentation is one of the most important aspects of learning a new technology. If you’ve ever written any code in your life, even “Hello, World”, you have likely come across documentation. Whether it was good documentation or bad is entirely up to you, the reader. What I aim to do in this post is to clarify what I, personally, look for in order to classify a document as “good documentation”. Ready? Let’s go.

Good Documentation is Up to Date.

There is nothing more frustrating than getting excited about beginning a new quest in learning something new only to find out the manual describes how and what to do in older versions, but not the current one. Before a product or project is released, the documentation should be modified to reflect the changes as necessary.

Good Documentation anticipates failure. Lots of failure.

When learning a new technology, many people don’t start with the documentation, but rather, end up looking at the documentation once they’ve hit a road bump. Documentation that anticipates this road bump will be extremely helpful to newcomers. When creating the documentation, try and think of ways the user could screw up (which, by the way, they will. Always).

Good Documentation does not contain specific terms without clear definitions.

I’ve seen this way too many times. The documentation will seem like it’s all find and dandy until one section you hit that reads something like:

In order to run this program on your machine, once you’ve installed the dependencies, update your path variable to reflect this change.

Of course, here I was just making something up so it kind of doesn’t make sense. But you get the point. Someone new to programming would be wildly confused, asking “What is a dependency?” or “What is my path variable?” or “How do I change my path variable?” or “What change am I reflecting?”.

Any time you mention something specific, please, explain it in great detail even if it does not directly apply to your project. This will make it much easier for newcomers to understand.

Good Documentation does not use words like “simply”.

What is simple to one person is not simple to another, necessarily. I’m sure many mathematicians would agree that it is “simple” to calculate a riemann sum, but that is not simple to do for someone who is just beginning algebra. The same concept applies to programming. There is nothing “simple” about it, as far as the documentation is concerned.

Good Documentation is extensive, and has many examples.

The most useful documentation out there is the documentation that is hundreds of pages long with multiple examples. When I say “examples”, I don’t mean one line of “Here is how you printf: printf(“hello”);”. If that was the only example given in the printf documentation, I would fear for anyone attempting to learn C.

Good Documentation has occasional pictures or even humor

This one is a bonus, as it completely depends on the tone of the documentation. If you’re writing corporate documentation whose audience may not appreciate your jokes, it might be best just to leave them out.

An important part of being a developer is writing documentation, not just writing code. If you’re ever tasked with writing documentation, be sure to do it the right way. Write good documentation that users and other developers can actually appreciate.

Jaken Herman

Written by

Husband | Software Engineer | Brewer of Beer

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade