Common mistakes in technical writing: #2 - Taking the bricks out of structured writing!

[Jordan_Stanchev]

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!

[Bob_McGlynn]

The challenge is with those consuming documentation. They are using search engines and those results take them to what they read first. That means the consumer can land anywhere and what happens if it's not the answer they are looking for? Like you said, we need to provide that answer to their question without it being buried in a long, generic topic.

Topic titles and the short descriptions are very important to provide the clues the consumer of the information needs to find the right place to land. That also means terminology is key - are we calling  something the same name everywhere it appears? Is that the same name that the consumer of our information is calling it? 

I agree that within an implementation or integration guide, the topics need to be organized to clearly assist our users through the processes and procedures. The challenge is that there are more variables and choices with enterprise software that depend on the customer's specific needs. We have to understand that those consuming that information find it for themselves and often have their own paths for organizing content.

It is important for us to provide a meaningful and helpful structure for our documentation. With the coming of AI, what metadata or tagging do we add to topics so, eventually, AI can serve up documentation in a way that personalizes it for the specific use case of the customer?

[Jordan_Stanchev]

Hi @Bob_McGlynn,

thank you for your comment! 

Like I often say, even the best-written documentation is of no use if people cannot find to read it in the first place! 

Topic titles, short descriptions, and proper organization of the content will help the AI better capture the information you try to convey to your end users.

If you want to see a real-live example, simply search a very specific question in Google, and you'll see how the search engine gives you the answer, instead of only a list of links to check! 

For example, when I search for:

"how to create a new topic in oxygen xml author"

Google answers:

Oxygen XML Editor supports both approaches.
...
Select one of the following actions:

1. Append Child > New - Select this action to insert the new topic as a child of the selected node. ...
2. Insert Before > New - Select this action to insert the new topic as a sibling to the current node, before it....

Adding Topics to a DITA Map - Oxygen XML Editor

But if I stay generic, when I search for: "how to create a new topic" it will just give me a link to sites to check. 

Obviously, in the first case, a very specific topic helped google to directly show the answer in the documentation. But in the generic case, that's not possible, because both the question and the possible answer(s) are too generic. 

And it is not so much about metadata and tagging any longer - if you properly structure and organize your content, the machine is already able to recognize the pattern even without special metadata on it.

So, writing in a structured manner, in a consistent way across your documentation offering is what will help both the human reader and the machines that try to serve the answer. 

Quite often I've seen technical writers simply writing down procedures ignoring the importance of the structure and then wondering why so few people can find and use the instructions from the documentation... Forgetting that the documentation must not only be technically accurate but also be FINDABLE and HELPFUL to the end user when needed!