Writing useful, structured and readable documentation isn’t that straightforward. In this post I’ll attempt to give some tips and tricks to help you improve writing documents. To be fair, nearly everything in this post applies to any communication, not just documentation. The same thoughts and approach can be applied to emails, meeting notes, presentations or even verbal communication.

Know and write for your audience

When writing any documentation, it’s always important to think about who will be reading the document. There will be a difference in the way you explain and write for developers versus business people. Ensure to keep this in mind, and to tailor the vocabulary and explanations towards your audience. Rereading your document from the perspective of your audience can also really help spotting any areas which need improving.

Context and content go hand in hand

Providing the necessary context is key. Give some introduction to what you are documenting, why you are documenting it and where it fits in the overall system. This will go a long way to help readers better understand the content further on.

Ensure to apply this concept to the content itself as well. When different context applies to your content segment, it could be a trigger to separate or structure your document differently, allowing you to provide proper context.

Just like the previous topic mentions considering the audience, you should also consider the type of document you are writing and tailor the context and structure of your document towards this. An analysis document for integration will look a lot different from api documentation or, for example, investigation notes for an incident.

Structure for readability and consistency

Structure your document in a logical and intuitive way. Opening a document should make your readers happy, and one way to turn off readers is the usage of inconsistent text styles and headers.

Use titles and subtitles to break up the document logically, apply context as described above to help decide where to separate content. Adding a table of contents gives readers an easy overview of what the document will contain by reading the headings, and allows easy navigation.

Consider maintainability

Aside from just writing your document in the now, it’s interesting to also think about the future of the document. Information is only interesting, as long as the information is correct and up to date. Sometimes it can be way more interesting to document high-level with in-depth reasoning about the high-level decisions, versus documenting very low-level details which are prone to change later on.

In general focusing on the key points, using clear and simple language, will help the document.

Examples go a long way

Adding some real examples, next to the theory, helps your readers to contextualise better and read the information in a different way. An example often can be used to tell more of a story than the text itself.

Consider your document editing experience

While ‘old school’ word documents still do the trick, there are many advantages to using a cloud solution. You can more easily share the content, there’s only one version of the truth, simultaneous editing by multiple people is possible, a full version history is maintained, linking to other documents and content is a lot more straightforward.

Aside from these benefits, these tools also offer functionalities which could be of great benefit to the reader as well. Widgets to show code with highlighting and copy functionalities, visual aids for illustrations, integrations with other software tools such as Figma, Google and diagrams.net are all very powerful to give additional value to your document.