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.
Loading ...
