Have you ever played the falling tower game, Jenga? In this game, you build short wooden blocks into a high and stable tower. Once ready, each player takes a turn to remove the blocks until the tower’s structure becomes unstable and it collapses with lots of noise and laughter. It’s always fun, but you should avoid playing this game in the evening – the neighbors rarely appreciate the noise!
Don’t you also get upset when writers play Jenga with documentation?
In technical writing, content should be logically organized and properly structured. Why? Because you need to provide a single topic as an answer to a single question. It can be surprisingly difficult to come up with only one answer and write only one topic to serve that purpose.
It’s always tempting to write content in a more generic way and put all the information in a single topic. After all, this requires no effort! Just writing what you think the answer should be and putting all the variations of the answer in the topic is so much easier than breaking it down and analyzing the different variants of this answer.
Don’t be tempted by this approach!
Your readers want the answer to their question, not a slew of answers where the one they need is buried with a dozen others or hidden under several levels of nested content.
The art of writing technical documentation includes building the holistic structure of your documentation topics by topic, answering one single question at a time, and leading the customer to the goal of your documentation – which is to solve their problem.
Let’s look at an example.
How do I paint a house?
It is a rather generic question. You cannot write one single answer to this question, because you need to know the context around it. How big is the house? Are there angles to be painted? What is the condition of the walls? Are there preparations to be made.
You see, when the answer is that generic, you need to lead the reader through a sequence of related topics. Each topic answering one-by-one the reader’s questions, leading them to the success of their project. Your documentation should try to follow the sequence of activities to be undertaken, regardless of the starting point.
XML templates - such as those offered by DITA - can assist in structuring your writing. Using DITA you can create Concept, Task, or Reference documents, with predefined elements, facilitating you in capturing the structure of your documents.
Make sure to give a proper structure to your documentation and never mix the content of the topics to mix the content of several answers! Keep the content of each topic straightforward and clear for the reader. Build it one brick at a time to create stable documentation that really helps!
Now over to you!
What do you think? Do you have rules for how you structure your documentation? Do you have ideas for different approaches or more dynamic approaches? Let us know in the comments!
2 Comments
