The Right Questions
No matter what you are working on, we will always ask you the same questions:
- Who will use it?
- Why do they use it? What problems do they solve?
- What do they need to use it? Do they need to know something beforehand?
- How do they use it?
- What do they get as a result? What can they do with it?
We will then ask the same, but with negations:
- When should they not use it?
- How to misuse it?
- If something goes wrong, how will they know? How do they cope with that?
These are useful questions. Technical writers, readers, and your team ask them. You ask them. So arm yourself with answers. Write them down, rearrange it in the order in which you would ask the questions yourself, plant them into your article, and expand on them as necessary. Cut the questions and answers that do not fit well, but keep them in mind. What is left is a draft full of content.
Five Ws and One H
Journalists use the "Five Ws and One H": who, what, where, when, why, how. This is a convenient form of this tool as you can throw the answers together in any plain text editor, on a scrap of paper, or in the chat window. Applied to documentation:
| Questions | More Questions |
|---|---|
| Who? | Who will use it? An engineer from a corporation? A coin trader? |
| What? | What is this feature? What does the user get as a result? |
| Where? | Every feature has a field where it is applied best. Every feature has limitations that form the border of that field. |
| When? | When should you use the feature? When should you not? Should you learn or do something before using this feature? |
| Why? | Why should you use this feature? Why not to use another feature? If something goes wrong, why? |
| How? | How to use this feature? How does it work? How do you know if it does not work? How do you make it work? If something fails catastrophically, how do you recover? |
I have written down answers for this page before I started working on it. I have not edited it afterwards:
| Questions | Answers |
|---|---|
| Who? | A developer from IOTA or IOTA's X-Team who has to document his work but does not know how. |
| What? | A set of questions. After you answer them, you get a solid general idea about a single topic. |
| Where? | An overview of a product or of a set of features, an article on a simple feature, an API description of a method. As it gives you only a broad view on a single topic, you would need a more powerful tool to plan a complex documentation structure. |
| When? | Best answered before you write, so you would have something to start with. These questions and answers make a good reference as you write or when you review your writing. |
| Why? | This is a simple tool. You sit down and answer questions. No meetings, no planning, fast to get the results. |
| How? | Sit down. Answer questions. It works because you answer the same questions that your reader would ask. It will go wrong if you give trivial answers: "Why users use this? Because it is useful!" You could then convert this questionnaire into an article. You would have to consider the structure, the order, and the way you raise these questions and present the answers. Otherwise, your reader might get confused. |
I have answered some questions in the very first section. I used other sections of this document to answer more. This example itself is the way I gave you some of the answers. The rest of the questions I have left out, but kept them in mind. As I was writing this article, more questions arose.
Try to apply both sets of questions to the same topic. Are the results different? Which one is easier to answer? Is one more restrictive than the other? Which set you would prefer to answer in which case?
Use Cases and User Stories
Questions like these are so ever-present so you might want to answer them even before you have started working on a feature. You would know your user better, state a clear goal, and would consider strong sides and limitations of your approach. You could use this tool in your ticket's discussion, or you could write down a bunch of use cases or user stories. They invoke different sets of questions, but offer similar benefits and put you in a similar state of mind.
Mind Maps
The right questions help you with the content, but they do not lay out the structure. To plan a structure of a complex topic, use a mind map instead. It can cover as much as a whole project!