Home » Technology » If Only the Documentation Looked as Clean as the Code

If Only the Documentation Looked as Clean as the Code

It’s been a year now since I started my most technical and challenging role in my career. I never intended to keep it secret. My writing didn’t include much about it.

This is my way of saying that it has. I’ve been exposed to many different computer systems over the years, created by different people. These systems forced me to quickly assimilate a large amount of technical knowledge.

In my role as a software engineer and writer, documentation has been a standout. It’s possible I should have seen this coming, but I was too busy keeping up to keep track of everything. I’ve come across some breathtaking documentation taking the reader on an adventure through the code. It was almost enough to make my eyes glaze from all the irrelevant text.

After reading hundreds of pages, my intuition developed for the difference between the lamentable and the exemplary. This is a distillation of my intuition.

The Platonic Form (at) of Good

What makes good documentation? Organization and visual tracking are fundamental to good documentation. These are some examples of it, in no particular sequence.

Callout boxes can be used to include reminders, cautions, and more. This practice helps to break up a wall that would otherwise consist of a monotonous text.

It’s also a good idea to sprinkle the page with colorful special formatting. This will make it easier for you to refer back quickly. If the reader knows the page, but wants to check out a specific caution, it is easier to scroll and find it than Ctrl F search, which could fail if they do not remember the wording.

Monospace is used for snippets of code that are either inlined or separated into a formatted section. If you have code on your documentation page, then it’s probably there to be used or tested in a particular project. Your code should pop out from the texture for either of these reasons.

Bonus points if the background of inline code is lightly shaded. This is done to make it easier to see during a scan. The larger chunks of code can be placed in a special box. Make sure that the code is easy to read.

Links are freely included. Authors of documentation should link to as many related pages as they can. Have you seen documentation that has too many links before? I’m not sure.

Tables organize relational data. Tables are great because they display associations. Tables can be used both horizontally and vertically. One item may have multiple attributes. Computers work on the basis of 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 can also be a great visual aid. My brain is more receptive to information if it’s presented in a table rather than a paragraph. Imagine that you need to remember as much information as possible about a page from two weeks ago by just glancing at it. What would you remember better, glancing at the page with a large table or just text?

Contact information is provided for the author and all teams involved. Documents can’t keep up with the changes in software. Knowing who to contact for updates can be helpful when that happens. Any contact information, including a person’s name, is helpful. However, the team listserv email is most useful. Teammates come and go but the listserv is usually the one that pings your team.

Included are diagrams. Diagrams are no different from tables, except that they’re more complex. Simple shapes are used to illustrate relationships, as our predator brains can process them easily. Microservices require diagrams to be understood because they involve a great deal of logic that extends beyond the particular application or services under consideration.

The Bad Habits That You Must Drop

In addition to the lack of these characteristics, there are a few others that make it difficult for you to consume documentation.

Poor organization. The most obvious sign of poor organization is an absence or inconsistent section headings. It is much easier to find what you are looking for if you have headings that you can scroll through, even if the table of content does not contain internal links.

The information is not verified. This one is sneaky because it can be tempting to assume it’s true if the document says so. Are you sure that’s true? Software can outpace the ability of developers to document it. Some authors are simply wrong.

There are two ways to recognize untrustworthy documents. The presence of words such as “work in process,” “tentative,” or “proposed” is one way to identify untrustworthy documents, especially if the page hasn’t been updated for a while. Was the project abandoned, were the ambiguous details resolved, or did the developers forget to update the site?

One sign that a document is not accurate is when it makes large claims, but does not provide links or any other pages to back them up. You should think twice about relying on the information you find.

Formatting is wrong Aside from the fact that sloppy formatting looks bad and can make a page unreadable for some, it shows that an author has copied and pasted the information without making any effort to contextualize and adapt the information. Sometimes the information can be just as accurate. However, the lack of context may lead the reader to the wrong conclusion.

It’s not to criticize authors who are already pressed for time. This has been a bad enough experience for me to say that looking for wonky formatting can be a way of protecting yourself.


Include a script, and tell readers to run it. Never, ever, Just run the script. In general, the intentions of the author are good. The author wants to relieve the reader of some cognitive load. Authors can’t be certain whether the reader’s case matches what the script is intended to do or have the skills necessary to determine this.

The author could have written a script that was sloppy or based on unrealistic assumptions. The script is not something you should ignore; it’s just important to read before implementing it.

Write the documents you want to read in the world

Unfortunately, you cannot force other people to write documents the way you would like them to. You can try but it’ll make you look like a jerk. The best approach is to The following are some of the ways to get in touch with us. Documentation that follows best practice is more useful. You’ll find your notes more useful, and they will also inspire others.

Although I have followed some of the constructive habits mentioned above from the start, I also picked up a number of them because I saw others doing them and thought to myself, “I am going to do that.” This person could be you.