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

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.

You Might Also Like:

No comments:

Powered by Blogger.