#2 Taking out the bricks of the structured writing!

Have you ever tried to play the game of Jenga – the falling tower? In this game you have short wooden blocks. You put them one over the other, to build a high and stable tower. Once ready, each player take turns to remove the blocks one of the other… Until the tower’s structure becomes unstable! And tumbles down with lots of noise and laughter from the kids. It’s always fun, but you should avoid playing this game in the evening – the neighbors get upset by the noise!

Don’t you also get upset when you play Jenga with your documentation?

In technical writing, the content is supposed to be logically organized and properly structured. The reason for that is that you need to be able to provide one single topic as an answer to one single question. What’s the trick? It is so hard to come up with only one answer and write only one topic to server that purpose!

It’s always tempting to write the content in a more generic way and put all the information in one 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, then braking it down and analyzing the different variants of this answer…

Don’t be tempted by this approach!

Your customers need to get the answer to the question they have. But they do not need an answer to a similar question. Or an answer to 5 more other questions (that they did not even asked about). Or the answer to the questions that is constructed by 10 other questions and lead them to 10 other documents to read through.

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 ultimate goal of your documentation – which is to solve the problem of the user!


How to paint the house?

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 that need to be fulfilled…

You see, when the answer is that generic, you need to lead the user into a sequence of related topics. Each of them answering one by one the questions of the user, leading them to the success of their project.

You need to write the documentation is such a way, that it is possible to organize the logic of your user guide into the sequence of steps that the customer needs to follow, no matter what the starting point is.

Structured writing can be eased by using the appropriate XML template, such as the ones offered by DITA. In DITA you can create Concept, Task or Reference type of documents, with predefined elements, allowing you to capture the structure of your document.

Always make sure to give a proper structure of your documentation and never mix the content of the topics to mix together the content of several answers!

Keep the content of each topic straight forward and clear for the user. Build it one brick at a time to have stable documentation that really helps!