Technical Stuff

New Technical Writer: The Four Dimensions Of Your User/reader

Posted by: buzz42 18/03.

By Barry Millman

OVERVIEW

To create an effective User Document, the writer must know who he/she is writing for. This article presents four dimensions (Skills, Attitude, Knowledge and Experience) for describing the User of your product (your Documentation Reader), and how to build a Persona that turns your generic User into an almost-real person. The article stresses the need to actually USE this information when structuring and writing your User Document.



GETTING INFORMATION ABOUT YOUR USER

The marketing department or product development team should be able to tell you who the intended User of the product is. (If they cannot, then the product is in big trouble.) Ask them to provide you with a complete description of the User. Ask them if their description can be make less strict (requiring fewer skills, ect.) and thus be applicable for a wider audience. Ask them how sure they are of their intended Users.



Ask them if they created a "Persona" (see below) to design the product. If so, ask them for the description of that Persona.



We will use this information to analyze your User in four dimensions. We will then re-build the ideal User into an almost-real person, who you can use to help design and write your User Document.



Timing: My estimate is that if the communication paths between you and the marketing and development teams are effective, then you should be able to complete this series of steps in a few hours spread over several days. This description of your User/Reader is an essential element in structuring and writing your User Document.



THE FOUR DIMENSIONS OF YOUR USER (Reader of your Document)

Four dimensions define your User/Reader. These dimensions are:



* Skills



What skills do you assume that your Reader must have in order to understand your User Document? (These are the skills that you assume that they have when they START to read your User Document... not the ones that you will teach them in the User Document.)



In a classic example of failure, a company that taught software programming did not specify that its students had to know how to use a particular computer word processor. As a result, students spent 80% of the class time learning how to use the word processor, rather than learning to write programs. The class was a failure.



List the skills that you expect your Reader to have.



* Attitude



Your Reader's attitude is almost always a combination of anger (impatience at having to read this stuff instead of using the product), and fear (something is not working the way your Reader expects it to). Write with compassion for your Reader. Are there other attitudes that may affect how your Reader uses the product and your documentation?



* Knowledge



What information do you expect the Reader to have when they read your User Document? Is there something that you expect your readers to understand or to have to figure out for themselves? If there are such items, then you should tell your Reader where to get the needed background information.



* Experience



Skills plus practice, yields experience. Are there any experiences that you expect your Readers to have, so that they can understand how to use the product or understand what you are writing? BEWARE of your Readers' experiences that may negatively affect how they use your product. One example is a product that radically changes the way that the User currently does things. Devote some space in your User Document to overcoming these problematic experiences.



WRITE FOR THE SAKE OF YOUR READER

These four dimensions spell out the word "SAKE." This reminds us to write for the SAKE of our Readers. You use these four dimensions when generating the topics for your User Document, as well as reviewing the material that you have written. These are topics for other articles in this "New Technical Writer" series.



Make sure that you tell your Reader about any SAKE assumptions that you make about them. Thus if you assume them to have a special skill, such as "welding steel" then tell them your assumption early in the User Document. If possible, tell them where they can get the background SAKE items that they might need. For example, if you assumed that your Reader has the skill to identify a certain bird, then tell them were to learn to identify that bird (perhaps with a link or reference to a birding authority).



You want to avoid situations like the one in the example above: the unstated requirement for knowing a specific word processor that ruined a programming class. Is the assumption that everybody knew how to use that esoteric word processor a reasonable one? The course developers should have checked with their sales department, since they sold the course to students who could not possibly have known about that esoteric word processor.



You really must clearly state (early in your User Document) any out of the ordinary assumptions that you make about your Reader.



YOUR READER AS A REAL PERSON

From the SAKE dimensions, and from the descriptions of the typical User of the product that you got from the marketing or development teams, you will create a real-as-possible person to represent your typical User. Such a representation is called a Persona in the product development industry. The Persona is also your User Document Reader.



If the marketing and development teams use a Persona, and they provided a description to you, then use their Persona. You may have to add some description to it.



If you have to create a Persona, follow these steps (overview):



1. Imagine the generic User of your product.



2. Focus on this User. Describe the User. Think about his/her background, education, family, hobbies, interests. The goal is to make your generic User as tangible as possible.



3. Perhaps give the User a name, and even spend a minute or two to find a photograph of this Persona.



4. Evaluate for yourself if this Persona is a good representation of the User. Make changes as necessary.



Think about how the Persona got your product (for example, did they purchase it, did it come bundled with some other product, was it a gift, etc.). Think about what they are most likely to want to do with your product.



Later we will use the Persona to help define the topics of the User Document, and to help you write the actual text.



CHECK

Once you have generated the SAKE items and the Persona, write them out, and let members of the product and marketing teams check them for accuracy. "Accuracy" means "how closely your Persona coincides with their (product and marketing teams) view of the product's User." Discuss these points and make modifications as needed.



USING YOUR READER

Unfortunately most courses and books about technical writing stop here in their instructions about "knowing your Reader." These courses and books expect you simply to keep your Reader in mind when you write.



But you can and should do much more with the description of your Reader. The Persona will help you structure the information in the overall User Document; it will also help you write each of the topics.



The SAKE dimensions will help you as you revise your writing. Here the SAKE dimensions will



* help you avoid using language your Reader might not understand, and

* help you avoid jumps in your writing that your Reader will not be able to make.



Other articles in the "New Technical Writer" series will describe how to use your Persona and SAKE dimensions to design and write your User Document. See the "Resources" or "Author Information" section of this article to find links to related articles.



About the Author: Barry Millman, Ph.D., has a Bachelor of Science in Electrical Engineering (1966, Carnegie Institute of Technology) and an M.Sc. and Ph.D. in Psychology (Human Information Processing, University of Calgary). He has been a consultant for over 25 years, an instructor, course developer, and award-winning speaker. For the past seven years he has been researching and creating resources to help organizations create great User Documents. Visit: http://www.greatuserdocs.com/ for resources to help you create the User Documents that your Product needs and your Users deserve.
Visit http://www.greatuserdocs.com/ReadingRoom.htm for more articles like this one.



Source: www.isnare.com

Comments