10 Structure Tips For Effective Technical Documents
in Professional on Technical writing, Software
When communicating technical ideas, writing and language skills are important, but structure can be importenter.
These are 10 suggestions on how to structure your technical documentation in a way that will make it easier for others to follow and to remember…
- 1 - Start with a backbone
- 2 - Write the conclusion first
- 3 - Sound certain
- 4 - Provide a map
- 5 - Use tables
- 6 - Cross reference
- 7 - Use Appendixes
- 8 - Have a table of contents at the top
- 9 - Keep a semantic version history
- 10 - Ask for Meta Feedback
1 - Start with a backbone
Before you get into writing your technical document, start by writing all the headings you think the document should have in order to achieve the outcome you have in mind. Sort of like writing your test first in code, this process will help you start to think about the people who are consuming your document and what they will need to know. And, as with TDD, you can always refine the structure as you implement the document.
2 - Write the conclusion first
The executive summary is not just for executives.
The first part of your document should tell the reader what the rest of the document is going to say. By doing this the reader can quickly decide if, given their current role, knowledge and priorities, it is important for them to read the whole of the document, only read certain sections, or even that just knowing the summary is sufficient for them.
3 - Sound certain
If you are unsure about what you are claiming or proposing this can result in long run-on sentences as you try to communicate your uncertainty, caveat your claims and provide all possible options. The result is long paragraphs that don’t really say much.
An alternative approach is to write down assumptions and risks in their own section. Then write the rest of the document with absolute certainty and conciseness, referring the reader to that section whenever you feel the need, and reminding them that these risks need to be considered, and those assumptions need to be true in order for your certainty to be true.
4 - Provide a map
A picture is worth a thousand words. A diagram is worth 10k.
Our brains remember stories, and maps intuitively. We don’t remember word lists beyond 3-4 items, and even then it takes some effort.
Creating and visualizing a mental model of what you are talking will help people to understand what you are talking about and remembering it later.
When creating a visual representation, stick to minimalist shapes, lines, colors and text. Avoid any intricate shapes and colors that don’t have meaning.
This is a good example. This is an example that makes my brain work too hard.
5 - Use tables
Tables provide a concise structure that is easier to scan, drill down into, and to come back later and find what you are looking for. Often a set of paragraphs or bullet points can be reduced to a much smaller table that is easier to fit into your head.
6 - Cross reference
Documents become much richer and more valuable when they link to other sources. You can also make them smaller or avoid duplication by linking out to other content.
7 - Use Appendixes
If you find yourself giving a long back story or side content in the middle of your document consider extracting it, and putting it at the end as an appendix, so that it does not clutter the main body of the document.
If the appendix has a value on its own outside of the document then extract and cross-reference it.
8 - Have a table of contents at the top
This makes the structure of the document visible, helps people know what they can learn from reading it, and helps people drill down quickly into what they are interested in.
9 - Keep a semantic version history
Most document writing tools these days automagically keep a history of changes. However this history won’t tell you why something changed, and if that change was a minor refactoring or a major rethinking.
This is why it can be useful to add a table near the top of the document that records a version, date, author and change column.
10 - Ask for Meta Feedback
When you have made some progress on your document it is a good idea to ask someone you trust for feedback on the structure, to identify what is missing or can be improved before you spend too long going down a sub-optimal path.
Allowing yourself a crappy first draft and getting rapid feedback will always result in a better outcome (this applies to the content and the structure!).
