How to write good documentation
I’m a weirdo. I know, that's a strange way to start an essay, but see — I'm the only person I know who always reads the instruction manual.
A while ago, I furnished my apartment and my bedside reading became a pile of manuals for house appliances. I enjoyed the refrigerator manual, but thought the ending was a little cold (…sorry).
Truth is, KitchenAid reader or not, nobody escapes from needing instructions in life and the experience is much more difficult if this document is incomplete or confused.
In software development and tech, documentation has multiple functions:
- Formalize processes and systems
- Learn out loud
- Help people answer their own questions
In all cases, both the writer and consumer benefit from the production of the material. If you want to participate in this knowledge exchange, here's a complete guide on how to write good documentation!
Before you start
Despite the parallel drawn earlier, making software documentation is much more complex than a device manual. That’s because there is no closed set of instructions that can be printed and never revised. Technology is constantly changing, and the most used systems are the most updated. Therefore, the most important documentation is the one that gets outdated faster.
That's nowhere close to encouraging, but it's remediable: most of the time, it's not the entire doc that is obsolete at once. It's the operational, technical details. So, one workaround is to separate the how from the why. How to use the system changes constantly, but why the system exists is a much more stable concept.
That was Etsy's idea when they did an experiment targeting “immutable” documentation. Following this concept to the letter involves other tools and making the process more complex, but we can extract a simple and very applicable lesson (TL; DR): whenever possible, avoid very specific details that can change. For example, instead of saying “We use the Roboto font”, you can give instructions to look for the project’s font in the <head> tag of the index.html file.
First steps
A blank page can be intimidating to the point of paralyzing even the most experienced writer. Here, we have the advantage of being able to start with a defined plan, without having to think too hard. I always follow three steps, in that order:
- Collect reference materials
- List content in macro topics
- Add details and technical part
Before I started writing the Astro Readme (design system at my former employer), I first opened all the references I would use. Then, I listed the information I already knew the document would need to contain. At that moment, I didn’t care much about the order:
Astro Readme- Instructions for importing the dependency into your project
- How to add the sources
- How to run the project locally
- Where to view online documentation
- How to edit the documentation
- How to deploy the documentation
- Official support for React
- Known errors for troubleshooting
Now that the page is no longer blank, it's much easier to proceed by detailing each of these steps. Before that, however, let’s go into detail about the structure of this document.
Title and introduction
The question you must answer when writing the title and the first paragraph of your doc is: “What is this document for?”
Try to come up with a title that clearly states what the text is about. If that's not enough, the first paragraph serves as a support to understand if this document is where they'll find the information they're looking for.
Mobile Accessibility GuideThis document is a reference guide for recent discoveries and new practices that must be disseminated in our project to continuously improve the accessibility of the mobile app. Right now, our efforts are focused on VoiceOver (iOS) and TalkBack (Android) screen readers.
Steps or items
We can now go back to that information list we mapped in the first step. Now's a good time to try to organize these steps or items in the same order that the reader will need to refer to them. For instance, "Install" and then "Usage".
The best way to present the content may vary depending on the type of process to be described. Step-by-step instructions are clearer if numbered; actions with no defined order can be organized into topics; a less technical issue can be well explained with a FAQ, and so on. When in doubt, test more than one format before defining.
Use very descriptive headings in each of them, to make it possible to quickly find the necessary information. This will also help you create a good index later.
Troubleshooting
In very technical docs, a "Troubleshooting" section can be especially useful for documenting known errors and obstacles and showing the way around them. It's important to keep this section up to date, as it's not uncommon to spend more time trying to fix bugs than actually developing.
Contact
In most cases, it's useful to leave contact info to answer questions and send suggestions by the end of the document. If you're writing a GitHub Readme, the contact section can also point to how and when to open an issue in the repository.
References
Including links to the materials used as a reference at the end of the doc is a good practice both for crediting authors and for readers who may be interested in diving deeper into those subjects.
Keep in mind
While creating this documentation, I suggest that you keep in mind some questions that help you cover as much territory as possible:
- Who will read this documentation — and what's their technical level?
Will this doc be consumed by people within a company team, or by the general public in an open source project? It's necessary to adapt the technical level or detail according to the reader, keeping the text as didactic as possible. Remember that "obvious" is a relative concept; sometimes, we think anyone understands what we consider simple, but this is not always true (I'm looking at you, impostor syndrome).
- Anticipate questions
That's basically an empathy exercise: try to anticipate any doubts that may arise throughout the text and answer them in the same place they appear.
- Single source of truth
The “single source of truth” concept calls for a single location to be maintained as a source of consultation for all matters relating to a subject. It is easier to keep a single place updated, so this is a good practice to aim for.
- Know when to stop
An unnecessarily long document is difficult to read and maintain. Try to discern how far you'll explain a topic within the doc or when it's time to link to a more specialized external tutorial. For more advanced people who may need more details, this is a way to point them in that direction without penalizing others with extra content.
- Stay in scope
Still on the previous item, be as objective as possible. If a tangent process starts to get too detailed, it may be necessary to separate it into another document.
- Link, don’t replicate
Avoiding details that can easily change dramatically decreases the frequency with which the document will be outdated. If the shifting details can be found in a more up-to-date external source (for example, information about a third-party plugin or dependency), it is better to link to it than to replicate that content within your documentation.
Enriching details
So, you covered all the previous points and want to take it a step further? Here are some details that enrich the experience of those who consume your doc.
- 1 reference = 1 link
Whenever you reference a concept or process, e.g. Markdown, find material on that subject and insert a link. Thus, a person who does not know exactly what that is or wants details can learn from a source you selected, which guarantees that you will be on the same page.
- Illustrate
Screenshots, gifs, illustrations, graphics, memes… Choose the best way to illustrate the content and use as many figures as necessary to make the text more dynamic and didactic.
- Information hierarchy
Those in contact with design are already familiar with this concept: the idea is to establish a visual hierarchy to facilitate quick understanding and localization of information. The most useful application here is to explore text formatting to create levels of title and subtitle (such as h1 to h6 headings in HTML), and thus to group macro and micro sets of information. We can also use bold, italics and even colors (like red in points of attention) to add intonation to the text, just as we would in voice speech.
- Practical examples
Whenever possible, add an example of the process described to illustrate its application in practice. This will always make all the difference in message clarity.
All done, now what?
Hold the urge to click “Publish”! Now’s the time to groom and polish your doc. Bear with me, it's just a few more steps:
- Read from beginning to end
When writing, it's normal to go back and forth several times and change paragraphs. Reading from beginning to end helps to review the cohesion of the text flow without interruption.
Time to drop a super important writing tip: the vast majority of people don’t read, they scan. Therefore, it's necessary to test the effectiveness of that information hierarchy, checking if it's possible to jump directly to a topic in the middle of the text and understand what is happening there. That’s what most people will do in your doc, no matter how good it is.
- Edit
When proof reading, in addition to finding improvement points, you should also wipe down, summarize and cut redundant or unnecessary parts. Remember: people don't read everything, so less excess is more clarity.
- Create the index
The index, or “Table of contents” as many call it, facilitates the preview of the content and also allows quick navigation. If the tool allows anchors (links that lead to points on the same page), use them.
- Ask for reviews
Ask people familiar with the documented system to review it, so they can validate that you have covered all points and have not forgotten anything. Then ask unfamiliar people. This is the most important part of simulating how a new person will understand the documentation, and is usually where you'll get the most feedback.
- Always update
After publishing the doc, it’s easy to forget about it forever. Technology documentation is never finished; the best practice is to elect a person or group responsible for maintaining it.
Another great trick for keeping docs updated is asking newcomers to contribute. They will read and use all those instructions for the first time, so that's a great opportunity to spot any outdated or missing info and improve them.
Final reminder
It's important to have well-written and updated documentation, but the software itself is even more important. We don’t want to get lost in detail and forget what our priority is, as the Agile manifesto preaches:
Working software over comprehensive documentation.
This priority is especially valid in the context of a closed company. But, of course, in a public or open source project, this motto has its caveats. After all, without documentation, it's very hard to understand third party code and impossible to contribute.
The final reminder is to always adapt the level of dedication to the documentation according to its context.
That's all for today and see you next time ❤
