New Technical Writer The Four Dimensions Of Your User Reader

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

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.

BONUS : New Technical Writer: Use The Persona To Create The Most Useful Section Of Your User Document

OVERVIEW

A good User Document includes sections on how to set up, use, and care for the product. However, to create a great User Document , the technical writer should use the Persona, generated in the analysis of the User/Reader, to create the topics for the most useful section of the User Document. This article describes this procedure.

THE MOST USEFUL SECTION OF A USER DOCUMENT

The most useful section of a User Document is the one that helps the User get what he/she wants/needs done right now!

Writing such a section might seem to be an impossibility. How do you know what the User needs to do now?

The only thing that you, as a writer, can do is to play the odds. That is, determine the topics that have the highest probability of being of interest to your User. And "of interest" means "getting what the User wants done, right now."

We created Persona (an almost-real representation of your product's User) in another article in the "New Technical Writer" series (see the links in the "Resources" or "Author Information" section of this article). We can use the Persona to create a topic list for this section.

USING YOUR PERSONA

This step in using your Persona is missed by almost all User Documents that I have seen. Yet this step will result in a User Document that is most satisfying to your Reader. Here it is:

Imagine your Persona using your product. Now, what are the main things that your Persona will want to do with your product.

As an example we will use a photo editing program (Acme FotoPhixer, a hypothetical product from a hypothetical company) that comes bundled with a point and shoot digital camera. Our Persona is a typical user of such a camera.

Ask: What does that Persona want to do with Acme FotoPhixer?

The short answer is that they want to improve their photos. HOW can they improve their photos with Acme FotoPhixer? In OUR words (not the words of the User) we could tell them how to:

* Rotate
* Crop
* Red-eye removal
* Adjust brightness & contrast
* Removing unwanted items from the photo
* Focus/Blur
* Save
* Print
* Share

These names are what we, the photography experts might use. However, "crop" may be meaningless to our Persona. In fact, we could move crop into "Removing unwanted items from the photo."

The "Focus/Blur" topic is interesting. If a photo is out of focus or blurred, there is really nothing that our software can do to improve it. However our Reader does not know this, but still wants to do it. We should include topic with this text: "It is impossible to fix the focus or remove blurring in a photograph. You might be able to improve this using the (Sharpen Effect) tool in FotoPhixer." (The () specifies a reference to the topic in the User Document.)

DON'T HIDE THIS SECTION

If your Reader cannot quickly find what he/she wants to do in your User Document, then the document has failed. Since we created this section to answer the User's pressing needs for the product, then we must make this section very accessible to the User -- they have to be able to find it easily.

"Fixing (Improving) Your Picture" is a PERFECT, User-oriented title. That is the correct title for this section. Don't bury this gold under titles such as: "Tutorial" or "Use FotoPhixer's Tools." These titles do not suggest answers to the User's questions.

You should make this section very easy to find in the User Document. It's the key section of the User Document. It has the information that most Readers want, most of the time (by your analysis). Place it prominently in the User Document.

SATISFYING THE READER IS EASIER THAN YOU THINK

Producing this section is easier than you think.

First, imagine that you were NOT going to include this section. Your User Document would still have to cover all of the features, tools, and user interactions for the product. You need to do that to satisfy your boss. It's also logical. If a feature is not described, then why is it in the product?

Thus you have created a topic list for a "classical" User Document.

Now we create our User-oriented section, "Fixing Your Picture." Here are the steps:

1. List each of the topics for fixing a picture, using titles that the Reader will understand.
2. Provide a brief overview, perhaps with a picture showing before and after the use of this fixing method.
3. Then list the steps for that topic, and provide links to the documentation for the relevant tools for each step

Done!

Actually, I would recommend using what I call a "Visual Index," which is described in the links in the "Resources" or "Author Information" section of this article.
Within Document Re-usability

We could call this organization method "within document re-usability." Here the writing for a topic exists as an item in the "reference" section of the User Document. By referring to that item when it is needed for performing a User-oriented task, we make the text do double duty. This results in reusability within the document.

HOW TO GET THE TIME TO WRITE THIS SECTION

Put less detailed effort into the documentation for the product's features that will be rarely used. For example, FotoPhixer includes tools to make the image look like it's made of stone, or produce 3D effects, etc. These are rarely used, and have a similar set of controls. Instead of detailing the use of each of these rarely used features, write a global usage, describe the controls, encourage the User to experiment, and remind them of the un-do and cancel capabilities.

You can create the "most useful" section with the time you save by not thoroughly documenting these rarely-used items.

THE BOTTOM LINE

You can make your User Document much more effective if you think about your User/Reader and what he/she wants to do with the product. Use this information to create an easy to find section in your User Document that meets your Reader's needs.