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.

 

About the author

Jonatan Lundin

Jonatan is a pioneering information architect backed by over 20 years dedicated to XML documentation, and designing for findability.

Post Comment

Comments

  • Vinish Garg 4 months ago

    Jonatan, I loved the guide as an easy reference while starting a new content project. I shared it with STC India Chapter group and the community loved it. Thanks you putting together this useful quick guide.

Categories

  • Information Design
  • Tech Writer Tips

Latest posts

Looking Back on 2016

December 29, 2016

Skribenta 5 Now Released

December 12, 2016

More from Blog & News