A year has passed since I started working in my current, most technical position. I had no intention of concealing it. Actually, it barely played a role in what I wrote.
I’m assuming it has by this time. My job has exposed me to numerous computer systems that have been developed over the years by numerous individuals. I’ve been compelled by all of these systems to quickly absorb a vast amount of technical information.
One aspect of my job that has particularly stood out to me is documentation, given that I enjoy writing and software engineering. I’ve seen documentation that almost made my eyes glaze over from walls of barely relevant text and documentation that just about made my eyes glaze over from the walls of barely relevant text, but I didn’t get to it while frantically keeping up with everything, OK.
I had an intuitive understanding of what distinguished the exemplary from the lamentable after reading dozens of pages. A deliberate distillation of that intuition is what comes next.
The Good’s Platonic Form
Fundamentally, organization and ease of visual tracking are what define good documentation. The manifestations of that are listed below in no particular order.
Examples, reassurances, and so forth. , which contain callout boxes. By doing this, you not only draw the reader’s attention to the content of the paragraph, but you also break up what would otherwise be a wall of text.
Making the page function as a quick reference is also a breeze with a dash of colorful special formatting. For example, if the reader is familiar with the page but needs to look up that one crucial caveat, it will be simpler for them to scroll until they find the box than to use Ctrl-F, which may not work if they can’t recall how the contents are phrased.
Code snippets are monospaced, whether they are inline or in a separate formatted section. If you have code on your documentation page, it is probably intended to be used or checked for in a project. These two arguments are sufficient for your code to emerge from the texture.
Bonus points if the background of inline code is lightly shaded. Once more, doing so will make it easier to identify during a visual scan. Large sections of code should be contained within something like a callout box. Make the code difficult to miss if there is a lot of it that is worth reading.
There are many links. Links to pages on as many related systems as possible should be used by documentation authors. I don’t believe I’ve ever seen documentation with too many links.
Tables contain relationship-based data. Tables’ ability to display associations is one of their best features. Both horizontally, where one item has several attributes, and vertically, where many items share the same class of attribute, these extend. Association is the foundation of computers. The foundation of almost all programming languages, an assigned variable, is nothing more than a value connected to a reference name or location.
Other excellent visual cues include tables. I can’t speak for everyone’s preferences, but my brain processes information better when it is presented in a table rather than a paragraph. Imagine that you only have to remember the most important details from a page you quickly skimmed two weeks ago. Looking at a page with a large table or one with just text alone would which serve as a better reminder?
The author and involved teams provide contact information. Documents don’t always update with changes in software. Knowing who to contact for updates in that situation is useful. Any information is helpful, even a name, but a team listserv email is the most practical form of contact. Individual teammates come and go, but the team generally receives pings from the listserv regardless of who is present.
There are diagrams included. Diagrams are more like tables in that everything that applies to tables also applies to them. Simple shapes that are easy for our predator brains to process to represent relationships are used as examples. Diagrams are essential for comprehending microservices because there is a lot of logic occurring outside of the specific application or service being considered.
You should give up bad habits like, well, bad habits
In addition to the aforementioned deficiencies, the following traits contribute to a frustrating document consumption experience.
There is a lack of organization. The most egregious example of poor organization is when section headings are missing or inconsistent. Even without an internally linked table of contents, having headings to scroll through makes it much simpler to distinguish what you’re looking for from unimportant details that will slow you down.
There are no indicators of the accuracy of the information. This is a sneaky one because it is understandably tempting to assume that something is true if it is in the document. Software outpaces developers’ ability to write it down, but do you actually have the factual evidence to support that? Sometimes writers are simply mistaken.
Unreliable documents can be recognized in a few different ways. Words like “work in progress,” “tentative,” “proposed,” etc. are present, for starters. , especially if it has been a while since the page has been updated. Did the developers forget to update the page, were those ambiguous details resolved, or was the project abandoned?
A document that makes bold claims without any supporting links and that is unsupported by any other page is another indication of questionable accuracy. If you observe this, pause before relying solely on what you have read.
The formatting is incompatible. Sloppy formatting indicates that the author copied and pasted without making any effort to contextualize or adapt the information, in addition to making the page look bad and possibly making it unreadable. The missing context can sometimes mislead a reader who is relying on the information’s accuracy, even when it is sometimes just as accurate.
This is not meant to disparage authors who try to squeeze in documentation production during a time crunch. I just witnessed how disastrously this turned out, so I would suggest keeping an eye out for any wonky formatting as a self-protective measure.
having a script included and telling readers to run it. Never, ever just execute a script. Usually, the author has good intentions. They want to relieve the reader of some of their cognitive load. However, the author can never be sure that the reader’s use case matches what they intended by the script or that they have the expertise to determine whether this is the case.
On the other hand, the author might have made irrational assumptions or just penned a hastily written script. The script doesn’t have to be followed exactly; you just need to read it before doing anything with it.
Write the documents you want people to read worldwide
Sadly, you can’t force people to write documents your way. Even if you try, you’ll just come off as rude. You should use a strategy that follows best practices when you write documentation. When you review your notes, it will not only be more beneficial but it will also motivate others to raise their standards.
A lot of the positive habits I’ve mentioned above I’ve started doing because I saw someone else doing them and thought, “I’m going to start doing that.” While some of them I’ve been practicing from the beginning. That person might as well be you.