If Only the Documentation Looked as Clean as the Code

 This month marks the one-year anniversary of taking on the most technical role of my current career. I have no intention of keeping it a secret. Indeed, it doesn’t affect my writing much.

By this point, I mean it’s clearly done. Over time, this role exposed me to various computer systems created by different people. All of these systems force me to absorb a lot of technical knowledge quickly.

Given my love of software engineering and writing, one of the things that stands out to me in my role is documentation. I probably should have seen this coming, but I didn’t while I was frantically keeping up with everything, okay? I’ve seen amazing documentation that walks the reader through code and documentation that makes my eyes glaze over from barely relevant text.

After reading dozens of pages, I developed an intuition about how to tell the difference between exemplary and pathetic. What follows is a conscious refinement of that intuition.

platonic form of good

What is good documentation? Fundamentally, it’s about organization and ease of visual tracking. Here are some manifestations, in no particular order.

Examples, reminders, warnings, etc. are enclosed in callout boxes. This practice not only directs the reader’s attention to its content, but also helps to break down the otherwise uniform wall of text.

Some colorful special formatting is also great for making the page double as a quick reference. For example, if a reader is familiar with the page but needs to find an important warning, it’s easier for them to scroll until they find the box than to press Ctrl-F to search for it, which may fail if they don’t remember the wording of the content.

Code snippets, whether inline or in separate formatted sections, are monospaced. If the code is in your documentation page, it’s probably meant to be used or checked in your project. Both of these factors are enough to make your code pop out of the texture.

Bonus points when inline code has a light shaded background. Again, this helps to identify it during visual scanning. Large blocks of code should be enclosed in something like a callout box. If there’s a lot of code worth reading, don’t miss it.

Lots of links included. Documentation authors should link to pages on as many relevant systems as possible. Have you ever seen a document with too many links? I do not think so.

Relational data is organized in the form of tables. One of the best things about tables is that they show relationships. They can extend either horizontally, where a single item has multiple properties, or vertically, where many items share the same class of properties. Computers are built on associations. That’s assigned variables, which are actually the cornerstone of all programming languages ​​– values ​​associated with a reference to a name or location.


Comments