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.
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.
OVERVIEW
You’re a non-writer who has just been assigned to write the User Documentation for your company’s new product. Your overwhelming emotion is fear, perhaps with some anger.
With any new activity there will be some anxiety. Writing may have added anxiety because of your writing experience while you were a student.
Writing User Documentation is not like the writing that you had to do in school. Those activities were filled with anxiety and “writer’s block.” In this article you will see how to overcome your writing anxieties so you can write a good User Document.
WHAT YOU’RE NOT WRITING
All writing and writing situations are not the same. Let’s differentiate writing a User Document from other types of writing and writing situations.
YOU’RE NOT WRITING A NOVEL
You don’t have to worry about a plot, characters, and techniques to make the writing flow. You do not have to worry about transitions from one section to another; you don’t have to worry about continuity. It is extremely rare for your Reader to read a User Document from start to finish; Readers usually only look up the information that they need at the time.
YOU’RE NOT ARGUING A POINT
You don’t have to determine a point to argue, think up arguments to support that point, and then convincingly present the arguments.
YOU’RE NOT WRITING A LABORATORY REPORT
While lab reports provided a structure for writing, it was usually over-restrictive and those doing the grading were very picky regarding that format and structure.
YOUR SCHOOL-WRITING EXPERIENCES
At the end of your school writing exercise there was a critic (your teacher). Your goal was to impress him/her with your writing, all the time being extremely careful to write grammatically, and follow the prescribed structure. Later we will get a “critic” (editor) to be on your side in the writing project.
Writing a User Document is Different. The team is on your side. (I am ignoring office politics.) Everyone wants to have a successful product, and good User Documentation is part of a good product.
Remember that other members of the team are human, also. They have their tasks to complete, and would probably prefer not to have to answer your questions. Be prepared (read background info, etc) before you ask questions.
STRUCTURE MAKES WRITING EASIER
The overall structure of the User Document will follow the interaction between the User and the product. Within that structure you will write components…pieces of the User Document, each dealing with a specific topic. Each component will have a defined structure: overview/background, the actual material, and additional information.
One benefit of working this way is that you will not be concerned with “writer’s block.” The primary cause of writer’s block is having making decisions (”what should I say here?”). An effective writing structure eliminates most decisions, and reduces your writing task to almost “fill in the blanks.”
In fact, some experienced writers find it difficult to write in a modular environment. They are concerned with writing elegant transitions from one section to another. You do not need to do this…you can write each component totally independently of the others.
Your task is to clearly provide the information that your reader needs, and make that information easily accessible to him/her.
You must cultivate an attitude of compassion for your Readers.
YOU NEED RESOURCES FOR SUCCESS
Whoever assigned you the writing project (your “patron”) is responsible for your success. Your patron should provide resources to assist you. One of the most important resources is an editor.
EDITOR
Your editor (if hired early in the project) can help you over many writing difficulties. For example, your editor can help you with wording problems as you write. Consult with your editor as you are creating the User Document…not just at the end.
Your editor is not your critic!
Your editor will reduce your worries about grammar and wording. Your editor is on your side; he/she is not an adversary or someone you have to impress (like your school teachers). Your editor can help you produce a good User Document.
ACCESS TO INFORMATION
Your patron should enable you to have access to the product developers, information about the product (a mockup of the product, marketing information, assumptions about the Users of the product), and the industry.
TIME AND PHYSICAL RESOURCES
You need time to do a good job, and the physical resources to get it done.
If you are in a hurry, and if you do not know any of the current fancy authoring tools and content management systems, do not bother with learning them.
Instead, investigate what your word processor will do. Can it be made to create PDF, HTML, RTF or text files? If so, then it is a fine candidate for this project. Learn how to use its basic capabilities, especially its concept of formatting “styles.”
TRAINING/GUIDANCE
Typically, documentation is started late in the project’s life cycle. As a result, the documentation production is always rushed. Taking a live writing course may be out of the question: there will be scheduling problems, and you will be away from the writing task while you are being trained.
A better alternative might be to take a computer-based course that guides you through the writing, and supports you via e-mail. Visit the links in the “Resources” or “About the Author” section of this article.
YOU NEED A WRITING METHOD
To simply gather the required information, produce an outline that gets approved, and go off to write the document, is a recipe for high-stress and possible failure. It’s high stress because at the end of your writing, you get everything evaluated at once. There is the fear of failure. Fundamental errors could result in a major re-write. Aaaargh!
Consider writing components (modules, pieces) of your document. Let a component sit for a while, review it, and then circulate it for review. This way you will know that you are on track early in the project.
Since components will usually be short and focused on a particular topic, your reviewers will actually have the time to read and comment on your components. Just providing a complete, massive document at the end of the project will discourage your reviewers from effectively evaluating the material.
Writing and having reviewed small chunks of text (as opposed to creating the entire document, and then having it reviewed) helps reduce your stress, enabling you to do a better job.
Recall a skill that you have learned. It may be driving a car, riding a bicycle, or solving differential equations. Remember how you got more comfortable as you worked at it. It is the same with writing your User Document in components. The first few components will be high-stress, since you are new to the process.
As you write and have your components reviewed, you will become comfortable with the process. The later writing will go faster and better because of the reduced stress. Your review team will know where you are in the writing process; they will see each component as you release it.
Contrast this with writing the entire document and then having it reviewed. Here the stress builds to a maximum at the hand-in and evaluation time. You never know — until the end — if you’ve made a fundamental mistake.
DEALING WITH REVIEWS OF YOUR WRITING
You will have each component reviewed by others on the product project. Consider their suggestions and criticisms of your writing. However try to leave your ego out of the equation. If a reviewer says “you got this wrong,” you should hear “this is incorrect.” Ask what is incorrect, and get the correct information. Correct the inaccuracies. Don’t be defensive.
If you can overcome your fear of criticism, you will be able to write more and write better. This fear will diminish as you produce (and have reviewed) each of the components.
Learn as much as you can about the product, its environment, and Users. If you are expected to be an expert and are not one, then use the excuse for any naive questions you may ask: “I am just simulating our product’s Users with this question.” (Use this technique sparingly.)
TWO MORE POINTS
Nobody writes the perfect User Document. Don’t strive for perfection. Doing so will prevent you from getting anything done.
Read. Read all sorts of published materials, especially other User Documents (especially for products similar to the one you are writing about). Learn from that writing. Be critical of it from the USER’s point of view.
FIRST THINGS TO DO
Learn as much as you can about the product that you have to write about, its users, and the product’s environment, before you ask questions (other than where to get information).
Visit the links in the “Resources” or “About the Author” section of this article. There you will find articles and resources to help you through this exciting task.
OVERVIEW
Stop confusing your Reader with the words you use. Your Reader is trying his/her best to understand how your product works without having to figure out your writing. Here are some writing guidelines to help you stop baffling your Reader.
SAME CONCEPT: SAME WORDS
User Documents are not meant to be entertaining. Do not try to be creative, especially by using synonyms for specific concepts in your product. When you talk about a topic use the exact same wording to describe (or name) the topic everywhere in your User Document.
For example, the “Same Concept: Same Words” guideline, says that if there is a control on your product called the “Activation Button,” then everywhere you talk about that button use the term “Activation Button.”
Don’t be “creative” and use words like “Activation Control” or “Start Control” to refer to the “Activation Button.” Using the different wordings forces your Reader to have to stop and think “Is this the same thing as ‘Activation Button’?”
DIFFERENT CONCEPTS: DIFFERENT WORDS
I bought something on the Internet that had a rebate available for it. When I ordered the product, I was given a “Tracking Number” to monitor the progress of my order. This is common for orders from large companies.
When I applied for the rebate, the rebate company used the same word, “Tracking Number,” but this time it meant “their rebate tracking number.” When their website asked for “tracking number” I entered the only one that I knew, the product ordering tracking number. I was wrong; the rebate number was a totally different thing.
The Rebate number is different from the order tracking number and should have a very different name from the order tracking number.
One might argue that “the rebate company is a separate company, and must handle rebates for all sorts of sellers.” Sure, but they can use a very specific name for their rebate tracking number. They can call it the “Rebate Identification Number.” That name would not be used by any selling company to track an order. The problem is solved. No User would confuse “Tracking Number” with “Rebate Identification Number.”
QUIZ
Given the information in the previous two sections of this Article, wouldn’t it be really silly if the rebate company originally called it the “Rebate Identification Number” and then unannounced switched to calling it the “Rebate ID”? Answer: Yes, it would be very silly. The change forces the Reader to have to ask, “Is this the same thing as the ‘Rebate Identification Number’?”
It’s not that your Reader is too stupid or lazy to figure out what you mean. It’s that your Reader has better things to do than to decipher your writing.
WORDS YOUR READER DOESN’T KNOW
Jargon is the shortcut language of any industry. Make sure that if you use jargon in your User Document, you explain what it means. If the writing project can afford the bit of time, I recommend that you include a glossary in your User Document. Define all the jargon, acronyms, and words that you might use in ways your Reader might not expect. A great example of the latter are “debit” and “credit.” The common understanding of these words is exactly opposite to those in the accounting (banking) profession.
TIP: Be suspicious of any words your spelling checker identifies. Ask yourself two questions when your spelling checker identifies a misspelled word:
* Did I really spell that word incorrectly?
* If it’s spelled correctly, am I certain that my Reader knows what the word (or acronym) means? If it’s not in the spelling checker’s dictionary it might not be in your Reader’s vocabulary.
DON’T BE AMBIGUOUS
I have a notebook computer running MS Windows XP. If I am using the Media Player and I press the keys to hibernate the computer (put it into an energy-saving sleep state), something warns me that hibernating will lose my place in the video. It then asks: “Do you want to continue? Yes/No.” Continue what?: Continue hibernating, or Continue watching the video? It would only take one or two more words to remove the ambiguity.
THE BOTTOM LINE
When you revise your writing, make sure that your Reader does not have to guess what a word might mean. If you mean the same thing as another concept, use the exact same name. If you mean something different, then use as different (unique) a name as you can. Define jargon, acronyms, and any unusually used words. Eliminate ambiguity.
Your reader is uncomfortable enough having to read your User Document, instead of using your product. Don’t make things worse by using wording that makes your Reader have to work out its meaning.
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.
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.
OVERVIEW
You’re a non-writer who has just been assigned to write the User Documentation for your company’s new product. Your overwhelming emotion is fear, perhaps with some anger.
With any new activity there will be some anxiety. Writing may have added anxiety because of your writing experience while you were a student.
Writing User Documentation is not like the writing that you had to do in school. Those activities were filled with anxiety and “writer’s block.” In this article you will see how to overcome your writing anxieties so you can write a good User Document.
WHAT YOU’RE NOT WRITING
All writing and writing situations are not the same. Let’s differentiate writing a User Document from other types of writing and writing situations.
YOU’RE NOT WRITING A NOVEL
You don’t have to worry about a plot, characters, and techniques to make the writing flow. You do not have to worry about transitions from one section to another; you don’t have to worry about continuity. It is extremely rare for your Reader to read a User Document from start to finish; Readers usually only look up the information that they need at the time.
YOU’RE NOT ARGUING A POINT
You don’t have to determine a point to argue, think up arguments to support that point, and then convincingly present the arguments.
YOU’RE NOT WRITING A LABORATORY REPORT
While lab reports provided a structure for writing, it was usually over-restrictive and those doing the grading were very picky regarding that format and structure.
YOUR SCHOOL-WRITING EXPERIENCES
At the end of your school writing exercise there was a critic (your teacher). Your goal was to impress him/her with your writing, all the time being extremely careful to write grammatically, and follow the prescribed structure. Later we will get a “critic” (editor) to be on your side in the writing project.
Writing a User Document is Different. The team is on your side. (I am ignoring office politics.) Everyone wants to have a successful product, and good User Documentation is part of a good product.
Remember that other members of the team are human, also. They have their tasks to complete, and would probably prefer not to have to answer your questions. Be prepared (read background info, etc) before you ask questions.
STRUCTURE MAKES WRITING EASIER
The overall structure of the User Document will follow the interaction between the User and the product. Within that structure you will write components…pieces of the User Document, each dealing with a specific topic. Each component will have a defined structure: overview/background, the actual material, and additional information.
One benefit of working this way is that you will not be concerned with “writer’s block.” The primary cause of writer’s block is having making decisions (”what should I say here?”). An effective writing structure eliminates most decisions, and reduces your writing task to almost “fill in the blanks.”
In fact, some experienced writers find it difficult to write in a modular environment. They are concerned with writing elegant transitions from one section to another. You do not need to do this…you can write each component totally independently of the others.
Your task is to clearly provide the information that your reader needs, and make that information easily accessible to him/her.
You must cultivate an attitude of compassion for your Readers.
YOU NEED RESOURCES FOR SUCCESS
Whoever assigned you the writing project (your “patron”) is responsible for your success. Your patron should provide resources to assist you. One of the most important resources is an editor.
EDITOR
Your editor (if hired early in the project) can help you over many writing difficulties. For example, your editor can help you with wording problems as you write. Consult with your editor as you are creating the User Document…not just at the end.
Your editor is not your critic!
Your editor will reduce your worries about grammar and wording. Your editor is on your side; he/she is not an adversary or someone you have to impress (like your school teachers). Your editor can help you produce a good User Document.
ACCESS TO INFORMATION
Your patron should enable you to have access to the product developers, information about the product (a mockup of the product, marketing information, assumptions about the Users of the product), and the industry.
TIME AND PHYSICAL RESOURCES
You need time to do a good job, and the physical resources to get it done.
If you are in a hurry, and if you do not know any of the current fancy authoring tools and content management systems, do not bother with learning them.
Instead, investigate what your word processor will do. Can it be made to create PDF, HTML, RTF or text files? If so, then it is a fine candidate for this project. Learn how to use its basic capabilities, especially its concept of formatting “styles.”
TRAINING/GUIDANCE
Typically, documentation is started late in the project’s life cycle. As a result, the documentation production is always rushed. Taking a live writing course may be out of the question: there will be scheduling problems, and you will be away from the writing task while you are being trained.
A better alternative might be to take a computer-based course that guides you through the writing, and supports you via e-mail. Visit the links in the “Resources” or “About the Author” section of this article.
YOU NEED A WRITING METHOD
To simply gather the required information, produce an outline that gets approved, and go off to write the document, is a recipe for high-stress and possible failure. It’s high stress because at the end of your writing, you get everything evaluated at once. There is the fear of failure. Fundamental errors could result in a major re-write. Aaaargh!
Consider writing components (modules, pieces) of your document. Let a component sit for a while, review it, and then circulate it for review. This way you will know that you are on track early in the project.
Since components will usually be short and focused on a particular topic, your reviewers will actually have the time to read and comment on your components. Just providing a complete, massive document at the end of the project will discourage your reviewers from effectively evaluating the material.
Writing and having reviewed small chunks of text (as opposed to creating the entire document, and then having it reviewed) helps reduce your stress, enabling you to do a better job.
Recall a skill that you have learned. It may be driving a car, riding a bicycle, or solving differential equations. Remember how you got more comfortable as you worked at it. It is the same with writing your User Document in components. The first few components will be high-stress, since you are new to the process.
As you write and have your components reviewed, you will become comfortable with the process. The later writing will go faster and better because of the reduced stress. Your review team will know where you are in the writing process; they will see each component as you release it.
Contrast this with writing the entire document and then having it reviewed. Here the stress builds to a maximum at the hand-in and evaluation time. You never know — until the end — if you’ve made a fundamental mistake.
DEALING WITH REVIEWS OF YOUR WRITING
You will have each component reviewed by others on the product project. Consider their suggestions and criticisms of your writing. However try to leave your ego out of the equation. If a reviewer says “you got this wrong,” you should hear “this is incorrect.” Ask what is incorrect, and get the correct information. Correct the inaccuracies. Don’t be defensive.
If you can overcome your fear of criticism, you will be able to write more and write better. This fear will diminish as you produce (and have reviewed) each of the components.
Learn as much as you can about the product, its environment, and Users. If you are expected to be an expert and are not one, then use the excuse for any naive questions you may ask: “I am just simulating our product’s Users with this question.” (Use this technique sparingly.)
TWO MORE POINTS
Nobody writes the perfect User Document. Don’t strive for perfection. Doing so will prevent you from getting anything done.
Read. Read all sorts of published materials, especially other User Documents (especially for products similar to the one you are writing about). Learn from that writing. Be critical of it from the USER’s point of view.
FIRST THINGS TO DO
Learn as much as you can about the product that you have to write about, its users, and the product’s environment, before you ask questions (other than where to get information).
Visit the links in the “Resources” or “About the Author” section of this article. There you will find articles and resources to help you through this exciting task.
OVERVIEW
Stop confusing your Reader with the words you use. Your Reader is trying his/her best to understand how your product works without having to figure out your writing. Here are some writing guidelines to help you stop baffling your Reader.
SAME CONCEPT: SAME WORDS
User Documents are not meant to be entertaining. Do not try to be creative, especially by using synonyms for specific concepts in your product. When you talk about a topic use the exact same wording to describe (or name) the topic everywhere in your User Document.
For example, the “Same Concept: Same Words” guideline, says that if there is a control on your product called the “Activation Button,” then everywhere you talk about that button use the term “Activation Button.”
Don’t be “creative” and use words like “Activation Control” or “Start Control” to refer to the “Activation Button.” Using the different wordings forces your Reader to have to stop and think “Is this the same thing as ‘Activation Button’?”
DIFFERENT CONCEPTS: DIFFERENT WORDS
I bought something on the Internet that had a rebate available for it. When I ordered the product, I was given a “Tracking Number” to monitor the progress of my order. This is common for orders from large companies.
When I applied for the rebate, the rebate company used the same word, “Tracking Number,” but this time it meant “their rebate tracking number.” When their website asked for “tracking number” I entered the only one that I knew, the product ordering tracking number. I was wrong; the rebate number was a totally different thing.
The Rebate number is different from the order tracking number and should have a very different name from the order tracking number.
One might argue that “the rebate company is a separate company, and must handle rebates for all sorts of sellers.” Sure, but they can use a very specific name for their rebate tracking number. They can call it the “Rebate Identification Number.” That name would not be used by any selling company to track an order. The problem is solved. No User would confuse “Tracking Number” with “Rebate Identification Number.”
QUIZ
Given the information in the previous two sections of this Article, wouldn’t it be really silly if the rebate company originally called it the “Rebate Identification Number” and then unannounced switched to calling it the “Rebate ID”? Answer: Yes, it would be very silly. The change forces the Reader to have to ask, “Is this the same thing as the ‘Rebate Identification Number’?”
It’s not that your Reader is too stupid or lazy to figure out what you mean. It’s that your Reader has better things to do than to decipher your writing.
WORDS YOUR READER DOESN’T KNOW
Jargon is the shortcut language of any industry. Make sure that if you use jargon in your User Document, you explain what it means. If the writing project can afford the bit of time, I recommend that you include a glossary in your User Document. Define all the jargon, acronyms, and words that you might use in ways your Reader might not expect. A great example of the latter are “debit” and “credit.” The common understanding of these words is exactly opposite to those in the accounting (banking) profession.
TIP: Be suspicious of any words your spelling checker identifies. Ask yourself two questions when your spelling checker identifies a misspelled word:
* Did I really spell that word incorrectly?
* If it’s spelled correctly, am I certain that my Reader knows what the word (or acronym) means? If it’s not in the spelling checker’s dictionary it might not be in your Reader’s vocabulary.
DON’T BE AMBIGUOUS
I have a notebook computer running MS Windows XP. If I am using the Media Player and I press the keys to hibernate the computer (put it into an energy-saving sleep state), something warns me that hibernating will lose my place in the video. It then asks: “Do you want to continue? Yes/No.” Continue what?: Continue hibernating, or Continue watching the video? It would only take one or two more words to remove the ambiguity.
THE BOTTOM LINE
When you revise your writing, make sure that your Reader does not have to guess what a word might mean. If you mean the same thing as another concept, use the exact same name. If you mean something different, then use as different (unique) a name as you can. Define jargon, acronyms, and any unusually used words. Eliminate ambiguity.
Your reader is uncomfortable enough having to read your User Document, instead of using your product. Don’t make things worse by using wording that makes your Reader have to work out its meaning.