Why is some documentation better than others?

First published: Dec. 6, 2022 | Permalink | RSS
None

None

Note: This was originally published on the Azavea blog, but I wanted to put this here in case that blog disappeared.

A specific odd example

As said above, documentation is more than just README.md and /docs pages. One of the bits we do well at Azavea, especially on the Civic Applications team, is using commit messages as documentation. This may seem odd to some developers, since many do not consider this to be documentation.

When looking at what may read at first as an odd piece of code, we check the git blame and see what commit and PR this piece of code came from. Ideally this PR will say what was trying to be solved as a whole and the commit will say what was specifically changed to do this.

Our local master of this technique is Senior Software Engineer, Terence Tuhinanshu of the Climate Applications team, who gave some great insight into this. At Azavea we try to write pull requests that address a particular issue and contain an list of commits that each make one change and title that change clearly in less than 50 characters (then limit to display in one line in GitHub), with optional details for further motivation. Each of these commits should appear in order, start with a present tense verb, and ideally read like steps in a recipe for how ton make this PR.

Here are a few examples of this that Terence has put together over the years, including one while Terence was into Gitmoji

The recipe part here is a nice analogy since recipes often fit a clear format that we often skim through and recheck each time we want to make a particular piece of craft. These steps should each be performed on their own and written with simple language to describe the action taken. A developer looking through this should be able to look through these steps and see how to recreate this themself or undo this work.

So, what makes good documentation?

There are many things that contribute to quality of documentation but to boil it down to a referenceable list we can say that good documentation is:

  • Centralized (as much as possible)
  • Consistently shaped
  • Structured to the needs of the reader
  • Holistic
  • But also referenceable

Thank you for reading!