February 9, 2017
46 Questions that Will Help You Produce Better Technical Documentation
Let’s say you’re uncertain about what to write in a manual because you’re not a true expert on the product you’re documenting. Maybe you have an idea about how to structure the manual and you ask a subject-matter expert (SME) for input.
The SME rejects your structure, saying they know that users want something other than what you suggest, such as task instructions and descriptions on system concepts.
You feel bad, fearing the SME is questioning your competence as a professional communicator.
Does this sound familiar?
Why does this happen over and over again in so many organizations? One reason is that many organizations lack explicit rules and principles that dictate what type of content should be written and why (some call it a content strategy).
In this guide I share a number of information architecture (IA) questions intended to help you get started developing your own set of explicit rules and principles. Once you have answered these IA questions, you will become more comfortable asking a SME for input.
Download the guide here: Information Architecture Questions
How to Use the Guide
As you set out to answer the IA questions and, ultimately, develop the explicit information architecture rules and principles of your content strategy, I suggest you organize a workshop and invite whoever could contribute—and then answer the questions together.
When developing the answers, you will make a lot of statements as claims; i.e., “We divide our users into three groups: X, Y and Z”. Be sure to also provide an argument that helps the organization understand why you make the claims you do. If you say you have three target groups, you can be sure that someone will ask: “So, what defines three, not two, or twenty-one?” Your argument will help you gain acceptance when someone in the organization, such as a SME who has not been part of developing the rules and principles, questions some of the concepts in the strategy.
As you will probably find out, all the questions boil down to one central question: What is the intention of a technical communicator?
In fact, my advice is that you start the workshop by answering this very fundamental question. I often ask beginner and experienced technical communicators what their design intention is. The answer is often, “to help users when they have problems.” This is a good start, but what does it really mean?
When I ask technical communicators what they mean when they say their design intention is to “help users when they have problems,” they often answer, “to provide the information users need to solve the problem”. Or, “to provide the right information on the right device at the right time.”
The first question in the IA guide is, “What rules, principles, and methods are you using to identify the type of information end users need?” The question is based on the view that the design intention of technical communicators is to “provide the information users need to solve the problem.”
So, how do you define an information need? And how do you identify the information that end users need? I would love to hear your answers to these questions.
- Information Design
- Tech Writer Tips