Home Article List

How I Write Documentation

In this article, I would like to talk about writing documentation and the practices I employ when I do so.

Table of Contents

Comprehensive Density

Comprehensive density is a rule I set for myself when it comes to technical writing of any sort. It is my fancy way of telling you to keep your writing short but thorough. Documentation is not meant to make the reader feel any sort of way - we are not trying to hook the reader into an interesting story or make them laugh, nor do they want us to. When I write documentation, I do so with two simple assumptions:

  1. The reader has never read my documentation before, including for whatever process/tool/standard they are currently reading about.
  2. The reader is in an urgent rush to find the information they need.

Every word takes time to read. Every missed technical detail has the potential to lead to confusion, and confusion takes time to resolve. Comprehensive density is a principle of balance - a balance between the reader’s time and the reader’s understanding. It is worth noting that these are not necessarily inverse. I think that after a certain point, the more time the reader spends reading, the less they understand.

Atomic Knowledge and Accessibility

Another principle I follow religiously is the idea of atomic knowledge. When I say atomic, I mean the smallest possible component. Atomic knowledge is a piece of information broken down and isolated into its purest form. For example, let’s say we are writing documentation on using Git; maybe we are hoping to explain the concept of a commit in some internal documentation. You can describe a commit without talking about branches, merging, stashing, or any of that fancy stuff. A commit is an atomic piece of knowledge, and the documentation that you write explaining what a commit is should also be small.

Accessibility is an important consideration when writing your documentation. I loop accessibility into the conversation about atomic knowledge because the methods of making information easily accessible are tied closely to the granularity of the information being communicated. Sometimes it is more accessible for a piece of atomic knowledge to get its own page of documentation. The readers attention is a valuable resource, and we can conserve that by limiting the page they are viewing to a single concept. In the case of several small, connected atomic concepts, those might better fit together as separate sections on a single document. The reader can then easily bounce between related topics.

Remember: At the end of the day, well-written documentation will end up as a bookmark that someone regularly references whenever they may need it. Make that reference digestible and easy to navigate.

Processes and Complex Concepts

Sometimes you must document things that simply cannot be feasibly broken down into atomic knowledge in isolated documents. Two such cases are documentation written for processes, and documentation written for complex concepts. Take, for example, the branching strategy of Trunk-Based Development as a process. This process is its own thing, but requires working knowledge of multiple smaller topics. An example of a complex concept could be branching, which requires knowledge of commits and merging for anything more useful than a layman’s explanation.

For such cases, it is wise to create a hierarchy of encapsulation. This might be a document on one process or topic with multiple sections, or it could be a top-level page with links to several subpages. Regardless, navigation is key. The user should be able to jump between subpages or different sections of a singular page. A table of contents or subpages would be useful here, especially if it is a document that you expect to be frequently referenced.

It is natural to reference other concepts that you or somebody else documented throughout your own documentation. In longer articles such as these, it isn’t always a bad thing to repeat yourself. In most cases, however, the statement you repeat should never be longer than a single sentence. Anything more than one sentence should be reduced to a link to another document or a section within another document (or even the same document). If the idea you are repeating isn’t saving the user any more time than if they just clicked a link into a new tab, then it is not worth being repeated.

What About AI?

I understand that, in the age of LLMs and generative AI as a whole, an article on writing documentation seems pretty pointless. With that being said, I am of the belief that any writing that a human is expected to read should be written by a human. I feel this is at least a deserved courtesy, but more likely a vital component in communication. I believe that LLM-generated documentation is some of the worst, most time-consuming documentation I have ever read. I acknowledge the survivorship bias inherit to this claim: Any documentation that I simply did not notice was written by an LLM is not considered in this evaluation. If you have figured out how to make LLMs write in a way that is equally useful as human-written documentation, fine. This article is not for you, and I would love for you to contact me to share your secrets (please!).

When I try to write LLM-generated documentation, I have found that models simply struggle in ways that they typically don’t when it comes to other applications. The biggest problem is that I haven’t found a way to make them write documentation to my standards. I use Anthropic’s Claude, which supports the SKILL.md judgment and context injection strategy. My skill for writing documentation includes a principle that I have in almost all of my skills, especially any skills that pertain to writing. The principle is as follows:

Employ a refined practice of comprehensive density. Verbosity is important only in conveying technical details, but excessive prose is counter productive and wasteful. LLM tokens and the reader’s time are both precious resources that must be conserved. No filler, no emojis, no excessive punctuation or prose. Be direct and spare no technical details.

In spite of this, LLMs continue to struggle writing documentation with the directness that I desire. I find myself getting frustrated as I read each extra word that it decided held enough weight in the communication that it must be included. Humans are inherently slow readers, and every extra word - every extra character - costs the reader valuable time. For this reason, I have found that arguing back and forth with an LLM on how to write documentation takes about as much time as writing the documentation correctly myself. It simply is not worth it.

Examples

Below are examples of some documentation that I have written: