Published on July 17th, 2023 📆 | 6169 Views ⚑
0If Only the Documentation Looked as Clean as the Code
This month marks a year since I took on my current and most technical role of my career. I didnāt intend to keep it a secret. Really, it just didnāt factor much into my writing.
By this point, Iām implying it clearly has. The role has exposed me to a variety of computer systems created by various people over time. All of these systems have forced me to assimilate an immense volume of technical knowledge rapidly.
Considering my affinities for software engineering and writing, one thing that has stood out to me in my role is documentation. I probably should have foreseen this, but I didnāt get to it while frantically keeping up with everything, OK? Iāve seen breathtaking documentation guiding the reader on a journey through the code and documentation that just about made my eyes glaze over from the walls of barely relevant text.
After reading dozens of pages, I developed an intuition for what separated the exemplary from the lamentable. What follows is a conscious distillation of that intuition.
The Platonic Form(at) of the Good
What makes good documentation? Fundamentally itās about organization and ease of visual tracking. Here are some manifestations of that, in no particular order.
Examples, reminders, warnings, etc., are enclosed in callout boxes. This practice not only directs the readerās attention to its contents but helps break up what would otherwise be a uniform wall of text.
A sprinkling of colorful special formatting is also great for making the page double as a quick reference. For instance, if the reader is familiar with the page but needs to look up that one important caveat, itās easier for them to scroll until they find the box than to Ctrl-F search for it, which might fail them if they donāt remember the contentsā wording.
Snippets of code, whether inline or in a separate formatted section, are styled monospace. If code is in your documentation page, it is probably meant to be either used or checked for in a project. Both are reasons enough for your code to pop out of the texture.
Bonus points when inline code has a lightly shaded background to it. Again, this is to help pick it out during a visual scan. Large chunks of code should be enclosed in something like a callout box. If thereās lots of code worth reading, make it impossible to miss.
Links are liberally included. Documentation authors should link to pages on as many related systems as possible. Have you ever seen documentation with too many links? I didnāt think so.
Relational data is organized in tables. The best thing about tables is that they show associations. These extend both horizontally, in which one item possesses multiple attributes, and vertically, in which many items share the same class of attribute. Computers are built on association. Thatās all an assigned variable, the bedrock of practically all programming languages, really is ā a value associated with a reference name or location.
Tables are another great visual cue, too. I canāt speak to everyoneās preferences, but my brain absorbs information better if it is laid out in a table compared to a paragraph. Imagine you have to recall as much as you can about a page you read only once two weeks ago, just by a quick glance. What would remind you better: glancing at a page with a big table or one with text alone?
The author and involved teams provide contact info. Software changes, but docs donāt always keep up. When that happens, knowing whom to check with for updates is helpful. Anything helps, even a name, but the most useful contact info is a team listserv email. Individual teammates come and go, but the listserv usually pings the team regardless of whoās on it.
Diagrams are included. Everything that applies to tables applies to diagrams, but more so. Relationships are illustrated with simple shapes, which our predator brains are good at processing. Diagrams are critical for understanding microservices because thereās a lot of logic going on beyond one particular application or service under consideration.
Bad Habits You Should Drop Like, Well, Bad Habits
Beyond the absence of the above, here are some characteristics that, by their presence, make for a frustrating documentation consumption experience.
Organization is poor. Poor organization takes many forms, but the most egregious is the absence or inconsistency of section headings. Even if there is no internally linked table of contents, having headings to scroll through makes it much easier to distinguish what you seek from irrelevant details that will bog you down.
There is no indication of information veracity. This is a sneaky one because it is understandably tempting to assume that if itās in the doc, itās true. But do you actually have the factual evidence to assert that? Software outpaces developersā ability to write it down. Sometimes authors are just wrong.
There are a couple of ways to identify untrustworthy docs. One is the presence of words like āwork in progress,ā ātentative,ā āproposed,ā etc., especially when the page hasnāt been updated in a while. Were those equivocated details finalized, did the devs forget to update the page, or was the project scrapped?
Another sign of dubious accuracy is a doc that makes big claims with no links and which no other page corroborates. If you see this, think twice before relying on what you read.
Formatting is mismatched. Besides the fact that it looks bad and may make the page unreadable, sloppy formatting shows that the author copied and pasted without any effort to contextualize or adapt the information. Sometimes the information is just as accurate, but other times the missing context can lead the trusting reader down the wrong path.
This isnāt to cast aspersions on authors trying to squeeze in documentation production when their time is already scarce. Iāve just seen this turn out badly enough to advise that watching for wonky formatting is just looking out for yourself.
Including a script and instructing readers to just run it. Never, ever, just run a script. The authorās intentions are usually good. They want to let the reader offload some cognitive burden. But the author can never be certain that the readerās use case aligns with what they intended by the script or has the skills to evaluate whether this is so.
On the other hand, the author may have relied on unrealistic assumptions or just written a slapdash script. You donāt have to ignore the script; you just have to read it before using it for anything.
Write the Docs You Want To Read in the World
Sadly, you canāt make other people write docs the way you want them to. You can try, but youāll just look like a jerk. The better approach is for you to write documentation that adheres to best practices. Itās not only more useful when you refer back to your notes, but it will inspire others to up their game.
While Iāve been following some of the aforementioned constructive habits from the beginning, a lot of them I picked up because I spotted them somewhere else and thought, āIām going to start doing that.ā That person might as well also be you.
Gloss