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


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 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.


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.)


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.


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


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.


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.


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.

Related Posts:

Powered by Blogger.