Rules and Tips
 for Writing Great User Documents

 

Table of Contents

Rules and Tips. 1

Bad Attitudes as a Writer2

Worst Attitude: “Everyone Knows That”. 2

Next Worst Attitude: “The User Can Figure It Out”. 2

Rules. 2

Protect Your Organization. 3

Legal Information. 3

Dealing with Outside Agents. 3

Get It Right3

The Important Question to Ask. 4

When Generating Topics:4

When Ordering the Topics:4

When Clustering/Grouping Topics:4

When Writing Topic Text: Ideas. 4

When Writing Topic Text: Writing. 5

Steps Should be in Chronological (Time) Order5

Reviewing and Revising Your Writing. 5

Improving Access to the Material5

At Every Stage of Your Writing. 5

NEVER Use Multi-Column Layout ("Newspaper Style") for an Electronic Document6

Your Writing Should Not Make the Reader Have to Think. 6

Where It Fits. 6

People as State Machines. 6

Ambiguity. 7

Your Balance and Judgment7

Readers’ SAKE. 7

Write so Your Readers WIN.. 8

When In Doubt—Don’t Leave It Out8

Overviews are Vital!8

Reader Ease. 9

Jargon & Special Words. 9

Access. 9

Graphics. 10

Overall Picture. 10

“Perfection is the Enemy of Good.”. 11

What to Think About when You Write. 11

When You Are Writing. 11

Don't Leave the User Hanging. 11

No Humor12

No References to Current Events or Entertainment12

Tips. 12

Provide Technical Information. 12

Use a Scrap File. 12

Mark Your Problems. 13

Say Things More than Once if Necessary. 13

 

 

Worst Attitude: “Everyone Knows That”

It’s never true.  Just because you know something (probably because you use that knowledge frequently) it does not mean everyone knows that something. 

If you have this attitude when you wrote, you will tend to leave material out of your User Document that your User may need.

Tomatoes.  Most of us keep them in a refrigerator.  However, storing them in a refrigerator will ruin the taste and nutrition of tomatoes.  Tomatoes should be stored on a kitchen counter at room temperature.  Does everyone know that?  What does everyone know about your product?

 

Thinking "Everybody knows that,"  means that you are writing with assumptions about your Reader's SAKE (especially Knowledge) that might not be valid. 
Be careful if you have the attitude that "Everybody knows that."  You could be doing a disservice to your Readers and your writing. 
When in doubt whether everyone knows something add a bit of text explaining what you assume they know, or tell the Reader where to find information that will explain what "everyone knows."
Be careful about assuming that just because you put something earlier in your User Document, that your Reader will remember (or even have read) that information.  When in doubt put a reference to that information (tell them where to find it, or provide a link to it if your document is electronic.

Next Worst Attitude: “The User Can Figure It Out”

The User does not want to have to figure things out.  The User is not reading a mystery novel or any other literature, where he/she has to think about what is happening.  When someone uses your product, they are using it to meet their own needs.

When someone reads your User Document, they are doing so in order to use your product effectively to meet their own needs.

Don’t leave things for the User/Reader to figure out for themselves.  It takes you only a few moments to include the material and will save many Users many hours in figuring things out.

Protect Your Organization

Perhaps the most important rule is to protect your organization. 

Legal Information

You do this by including the proper legal information where a Reader can easily find it. This information includes:

O     Disclaimers (regarding accuracy or content of the User Document)

O     Warnings and Cautions (anywhere the User can get hurt or do damage to persons, property, data, etc)

O     Warrantee information

O     Trademark Information

O     Copyrights

O     Any other information that your legal department feels should be part of the User Document

Dealing with Outside Agents

An Outside Agent is anyone outside your organization  (company) who works on the User Document.  This includes editors, graphics artists, web developers, etc.

Make sure that any dealings with these outside agents includes clear contractual information regarding:

O     Ownership of the work they do (your organization must own it)

O     Confidentiality

O     Deadlines

O     Payments

 

If you release any copies that are not the final version of the User Document or part of it, for circulation either within or outside your organization, you should indicate that the copy is a DRAFT.

 

Get It Right

No matter how good your writing, no matter how well it suits your Reader's Skills, Attitudes, Knowledge, and Experiences, no matter how well it meets the Reader's Wants, Interests, and Needs, your User Document fails miserably if it does not accurately reflect the product it is documenting.

While that sounds logical, I want to give you a very real example where a big company failed:

ACM (the computer division of Acme) really messed up in their User Documentation for their QuikRestore software.  They failed on their website by not saying that Users will download the deluxe version of the product.  The deluxe version requires that the old version must be deleted before installation.  However, the non-deluxe version (which a User thinks he/she is downloading) does not need to have the previous version removed.  So the User does not remove the old software before installing the new.  The install fails with a message saying that the old version must be manually removed.

Aha, but the User should be pleasantly surprised that he/she is receiving the deluxe version for no additional cost.  Maybe so, maybe not, let's continue the saga.

The deluxe version supposedly enables the User to delete the file where the backup is kept.  The on-line User guide presents the actual steps about how to do it.  Unfortunately there is no "delete existing backup" button anywhere in the product, as the on-line User guide describes.  The document is "not right," it does not match the product.  The beautiful documentation renders the product useless.

The Important Question to Ask

Ask yourself this question over and over and over again as you list topics, organize the topics, write, review and revise the material for your User Document:

"Given the Skills, Attitude, Knowledge and Experience (the SAKE) of the Reader/User:

What do I need to tell them now?"

Here is how this question is used in the various stages of writing your User Document (or any other thing you write or any speech you give).

When Generating Topics:

"Given this User, given this product, given the goals of my document, what do I need to tell my Reader now?" 

In this case, it's a list of topics.

When Ordering the Topics:

"Given these are the topics I have chosen to include in the User Document, what do I tell them now?"

That is, given what they know and I have just told them (which they might not have read!) what should I tell them next?

When Clustering/Grouping Topics:

"Given what my Reader is trying to do now (that's why he/she is reading this part of the Document), what do I need to tell them now?"

This tells what topics go together as a group.  I am a believer that people work in modes or states.  That is, they tend to think along the lines of your discussion, or the problem that they are trying to solve. 

When Writing Topic Text: Ideas

"Given this topic that I am telling the Reader about, what are the ideas that I need to get across to the Reader?"

Or, "What steps does my Reader need to take in order to meet this topic's goals (to do what he/she needs to do)?"

The first step in writing about a topic is to be clear on the ideas you need to present about that topic.

When Writing Topic Text: Writing

"Given that I am trying to present an idea, what do I need to tell my Reader about that idea?"

What do I need to say to get that idea across to the Reader?  In some cases this could be just a bullet point, in other situations it could be one or more paragraphs of text.

Steps Should be in Chronological (Time) Order

Wrong:  "Close the barn door after making sure the horse is inside."  If the Reader were to perform the actions as they are written, the door would be closed, and the horse would not be in the barn.

Correct:  "Make sure the horse is in the barn, then close the barn door."

Reviewing and Revising Your Writing

"For each idea that I want to get across, am I saying what I want to say?  Am I saying it in a way that my Reader (given his/her SAKE at the time) will understand?"

"Do all my ideas (about a topic) contribute to the topic?  Have I left out anything that I need to tell the Reader?"

"Do all of the topics fit together to meet the goals of the document for the intended Reader?"

Improving Access to the Material

"Given that my Reader is reading this, what other information do I need to tell him/her about this?"

This means that wherever your Reader is in your User Document there could be other information that might benefit the Reader.  Within reason (you cannot have links to everything on every page of your document) tell the User where to find more information about the current topic that would help the User.

A fantasy:  many software products have context-sensitive help.  Pressing a "help" key brings up the part of the documentation that is relevant to what the User sees.  It would be nice to have context-sensitive User Documents.  Thus if someone is reading an electronic User Document, and they do not understand what's on a page they could click a "help" button and see a page of related information and links to related information about what they were reading.  For example, if a User clicked for "document help" when viewing a diagram, the "document help window" would contain a legend giving the meanings of all the symbols on the diagram.

At Every Stage of Your Writing

Keep these questions foremost in your mind when you write:

O     “What do my Readers want/need to do with the product now?”
Always remember that your Readers/Users use your product to meet their goals, needs and wants.

O     “What will my Reader ask here?”
Examine your writing from the Reader’s point of view.  If they might have a question, then answer it.

O     "What do I need to tell my Reader now?"
What is the next information or step that I have to tell them

O     "Does what I wrote fit with the product?"
Does your writing match the product that the User is dealing with?

 

NEVER Use Multi-Column Layout ("Newspaper Style") for an Electronic Document

Your Reader will be constantly scrolling up and down the page in order to read your material.  Multi-column layout is fine for printed documents, but terrible for those to be read electronically.  When in doubt, lay out your writing in a single column on the page.

Your Writing Should Not Make the Reader Have to Think

Stimulating thought is great for educational and fictional material.  It has no place in User Documentation.  User Documentation exists to help the User get on with the User's tasks.  In most cases your product is a tool to enable the User to reach his/her goal.  The User Document should provide answers, not questions.

Where It Fits

People work better, learn better, and will be more successful with your documentation if they know where and how things fit together.  For example, if your document is part of a set of documents, you should explain (visibly at the beginning of each document in the set) all of the components in the document set and what each of them cover. 

If someone is to use your product, it is easier for them if they know how the product fits into their lives and changes how they do things. 

The general idea: give the Reader the “big picture” before you focus down into the details.  To prevent the “forest and trees” situation (someone can’t tell the forest from the trees), tell your Reader about the forest first, and then present the trees.

People as State Machines

When your Reader is using your documentation for help, they are pretty much concentrating on the problem at hand.  It might be "how to format text" or "how to set the clock."

Your document will be easier to use if you ask yourself at each point in the document:

"What is the Reader using this part of the document for?"  In other words, what is the Reader trying to do now.

If you can answer this question then shape the material in that area of your document so that you

·         Provide the information that they need to do what they want to do

·         Minimize distractions.  Everything in that area of your document should focus on what you see the Reader as having to do.  Cute graphics can be distracting.  Some people who use Microsoft Word find the "Office Assistant" (an animated figure) an annoyance.   

·         Provide links or references in your document to other related information.

Ambiguity

I don't know where I stand on the topic of ambiguity.  I don't know whether to ask you to eliminate all of it, or leave it in where accuracy just doesn't matter.

I am talking about ambiguity of your instructions and text.  Let me give you an example:

I have a pH test kit to check the acidity of the water in my pond.  Its instructions say to add 3 to 5 drops of the indicator solution to the water sample.  This brings up the obvious questions in my mind: "Is there an effect of adding the different amounts of the solution?"  "Should I always be safe and add 4 drops?" "Do the different amounts truly not matter?"

Perhaps it would be better if the instructions specified a particular amount ("add 4 drops") and then went on to say that the amount is not critical, it could be anywhere from 3 to 5 drops.  This is so people would not feel that they had to re-do the test if they accidentally added 5 drops.

I'm not sure of the answer.  Just be aware that such ambiguity could be a problem in the minds of some of your Readers.  I'm sorry I cannot be of more help to you.  I use 4 drops.

Your Balance and Judgment

When you are writing, and when you are following the guidance in this Course, don’t accept every principle.  Use your own judgment.  In most cases, I say, “consider doing” doing something…not “do this.”  Look over the ideas that I present, and accept or reject them based on each specific writing situation.

For example, I say something like “avoid passive sentences (“passive voice” it what it’s called).”  Of Course you can still use some passive voice in your document. 

Readers’ SAKE

As you plan and review your writing keep the Readers’ SAKE in mind.  This acronym refers to the Readers’:

·         Skills

·         Attitude

·         Knowledge

·         Experience

You must take this information into account when you are generating topics to include in your User Documentation, and also when you are reviewing and rewriting the drafts of the User Document.   (While you are actually writing, your goal should be to get your ideas on paper.)

You can assume that the SAKE changes while reading your document, depending upon the kind of document:

·         Tutorial or Course
The SAKE may change based on what the Reader learns

·         Reference Material
Since the Reader jumps into this material at any point (based on the access methods you provide) you should assume that the SAKE at any point is the same as you assumed at the “start” of your document.

·         Tour
Although this is taken in the order that you set up, the User merely wants to be shown what the product does and how the product does things.  You should not assume any learning in the Tour, and thus you should assume that the User’s SAKE at the end of the tour is close to the SAKE at the beginning.

Write so Your Readers WIN

Write for the Wants, Interests and Needs (WIN) of your Reader.  Examine the operations that they need to do with your product in the four time epochs:

·         Overall

·         Before Using the Product

·         While Using the Product

·         After Using the Product

Aim your document to help them (based on their WIN) at each of these time periods.

Yes, this is the most difficult aspect of writing User documentation.  You must put yourself in the User's shoes when you are writing your document.  Think always about how the User wants to use your product and how your document can help them succeed.

When In Doubt—Don’t Leave It Out

If you are debating about whether to include a term in your glossary, or provide an additional explanation, or a reference to some related information, follow this rule:

When In Doubt—Don’t Leave It Out.

This means that you should include the information in your document.  If you find that you don’t have room for it in the User Document, then you can consider putting it on your Web site that supports the product (Internet Supported Product).

Overviews are Vital!

The document and each portion of the document should have an Overview or Introduction.  This tells the Reader

·         Is this relevant to me

·         Where does this fit in with my life

·         How does this fit in with the product

·         What are we going to discuss here

 

Reader Ease

Your Reader should not have to slow down or stop reading in order to understand what you have written.  Your writing must be clear, and directly to the point.  The less interpretation that your Reader must make in order to get your meaning, the better.

For example, a sports radio should use the word "exercise" rather than "train" when describing the product.  "Train" has all sorts of meanings which would make things slightly more difficult to understand than the more familiar "exercise."  (I'm sorry, I am splitting hairs here.)

In short

·         Don’t use fancy words

·         Feel free to use more words if necessary in order to explain your point

·         Write to what the User needs: Their WIN: Wants, Interests, Needs

Jargon & Special Words

Be careful when using jargon and any “special words,” words or phrases that you use in a unique way.   If your Reader does not know the meaning of the jargon or special words, then you have created the possibility of confusion.  It's safest if you assume that your Reader does not know the meaning of your jargon.

The solution is to define jargon or special words directly in your text. This is in addition to including them in the document’s Glossary. 

Notice how I defined “special words” in the first sentence of this section.  Alternatively, I could have used parentheses to define “special words.”  For example: Be careful when using jargon and any “special words” (words or phrases that you use in a unique way).

Be consistent with your jargon and special words.  Make sure that if you are using special words that you use them exactly the same each time.  You, as Reader, would clearly have to slow down to understand my writing if I used “special words” in one place and “special phrases” or “unique words” in another part of my document.

Access

Your document must provide great access to its contents.  Depending on whether your document is in paper or electronic format, you could provide access via:

·         Table of Contents

·         Headings and Titles on a Page

·         Carefully-Selected Bold Text within Paragraphs

·         Index

·         Electronic Search

If you are creating a Reference Manual, you might also wish to provide access via a “How To” section.  In this section you would list many of the common operations that a User might wish to do with your product, provide an overview for each, and refer (or electronically, link) to the reference portion of the document for the lower-level details.

With any form of access, you must assume that a Reader will drop in on any topic in your text.  This could be a problem to a User who doesn’t understand some of the background concepts at that point in the text.  One solution is to refer to other portions of your document where you explain the concepts you are currently using.  Of Course you could get into the situation where you never do any writing – all you do is keep referring to other sections of the document.  In that case, you have taken things a bit too far!  (See the discussion of Segments in our Glossary.

Be Aware: The names that you have chosen to represent something about your product might mean nothing to your Reader/User.  Think of synonyms or aliases for the names of concepts related to your product.  Provide those aliases in such a way that the Reader can find the material by using an alias, rather than only the names that you have selected for the concept.

 

Graphics

Use graphics (pictures, drawings, tables and charts) to help explain the material to the Reader.  The graphic should provide information which

·         Shows how it relates to the product

·         Shows how it relates to the document

·         Makes its point (via its caption)

·         Is Clear: all symbols on the graphic are explained

Overall Picture

Early in your document you should have a picture of your product (for a software product, you can have the main operation window, showing its menu items, tools, etc).

Identify all Points of Interaction on the product.  Refer (or link) to the page in your document where you explain that Point of Interaction. This makes life with your product much easier for your User, as they can find the description/explanation of each component of your product more easily than if they had to search for the information. 

Goal:   Perhaps a goal of great User Documentation is to be complete enough to put your training department out of work.  Just a thought.

“Perfection is the Enemy of Good.”

In fact that is not totally true.  Perfection is the Enemy of Completion.  Striving for the perfect document (instead of a really good one) will prevent your ever completing the task (I am writing this rule as much for myself as for you!)

What to Think About when You Write

When you create a User Document, here’s how you should think:

·         When you create a topic list and organize the list: Think about your Reader
When you organize your document and are generating topics to include in the document, think of the Readers’ abilities and needs (their SAKE and WIN).  Think of the material that you should include that would take the User from where they are at the start of your document, to where they should be when they finish your document

·         When you write the material for each topic: Think about your Fingers
When you do the actual writing, you only concentrate on the writing.  Get your ideas down (in writing, on a voice recorder, in the word processor).  Write fast...that actually makes things easier for you. Do NOT work on making your words “perfect.”  We discussed this in “Writing: Overview & Background.” 

·         When you revise and review the document: Think about your Reader
When you review the document (and make your revisions) you should be deeply concerned about how your Reader can follow your writing. Your writing must be clear and easy to follow.
Make sure that your topics will effectively tell the Reader what they have to know in order to be successful with your product.

When You Are Writing

·         Don’t worry about Spelling

·         Don’t Worry About Grammar

·         Don’t do any Formatting (except, perhaps for boxed text, to add information related to but not central to your writing)

·         Do not use bold text for emphasis—use italics or underlines

Fix the spelling, grammar and formatting when you review and revise (and provide good access to) your writing.

The goal when writing is to get your ideas down “on paper”

Don't Leave the User Hanging

The instruction document for the Heath/Zenith Motion Sensor Light Control leaves the Reader in a weird place.  Here's the statement in that document:

Some codes require installation by a qualified electrician.

There are two major errors in this one statement.

·         Error 1: The User does not know what a "code" is.  This is a consumer product.  The average User does not know what "code" means.  Perhaps the document should say "locations," "situations" or “laws” instead of "codes."

·         Error 2:  The User was left hanging.  Upon reading this statement, the User now has a question: "Is a qualified electrician required in my code (whatever that is)?"  The document should suggest how or who the User might contact to determine the requirements in his/her area.

No Humor

Please do not try to include any humor in your User Document.  Including humor in your User Document will

O     Confuse your Readers (especially those Readers whose first language is other than the language of the document)

O     Make your document harder to translate into other languages

 

No References to Current Events or Entertainment

If you make any references in your User Document to current events, television shows, etc, then your document will be dated.  You will confuse the Readers who are not "in the know" about those transient topics. 

Leave those references out!

You can (if you really feel that it is worth it) make reference to classical literature (perhaps Shakespeare).  However, including these references may still alienate your Readers who are not familiar with the reference.

Provide Technical Information

(Especially if your product is software.)  Somewhere in your document, perhaps in an Appendix, tell the User how your product works, and how they can adjust the various parameters to make it work properly.  Provide enough information so that some slightly more technical savvy Users can troubleshoot things if there are problems.  Mention this Appendix where relevant in your document.  It’s amazing how providing this information can assist your Readers in solving their own problems, saving calls to your (expensive) technical support lines.

 Use a Scrap File

Sometimes it’s very difficult for a writer to simply cut out some text.  You just don’t want to lose it.  My solution is to create a scrap file for your editing.  Whenever you have a piece of text that you feel needs to be cut, then cut it out of your document, and paste it to the scrap file.  Keep that scrap file…you may want to get some information back from it.

Typically, I name the scrap file something like "scrapYYMMDD" such as "scrap030318".  This makes the files distinct, and provides a unique year (YY), month (MM) and day (DD) as part of the name.

Mark Your Problems

As you are doing anything with your word processor (outlining, writing, whatever) you will come to situations where you need more information, or need to add clarification, or add a graphic, or add a reference to something else, or whatever.

Don’t let these situations stop your writing.  Instead use a set of symbols (I use three question marks, as ???) to mark your problem point.  Later, you can search the document for the set of symbols to find those problem points.

Further tip: don’t just mark the problem points.  Add some words that will tell you what the problem was.  Here are some of my examples:

·         For a graphic I feel should be inserted:
???graphic showing orchid and its parts???

·         For a link to the Web or anyplace in my document:
???link to Igetitnow Home Page???

·         For a place where I want to add an example:
???example of how to set up the antenna???

·         For a place where I want to add some clarification:
???clarify jargon???

Note that the first word following (no space) the set of symbols (my choice is ???) tells me what I need to do there.  Thus I could find all of the places in my document where I need a graphic by searching for “???graphic”.

Note also that I use a second set of the symbols (???) to indicate where the comment to myself ends.

I prefer to use a string of several symbols, rather than a single symbol to mark the problems in my documents.  Any single character on my keyboard might appear in the text of my User Document.  A string of three question marks (???) should not.

Choose the set of symbols that you would not normally use in writing your document.  I use three question marks as my problem identification symbol.   I cannot find a situation in my writing where I would need three question marks in a row.  Can you?

 

Say Things More than Once if Necessary

 

There seems to be some kind of fear in the User documentation industry of saying something more than once in a User Document.  This desire never to repeat any text results in some messy documentation.

Suppose there are two modes of operation for a product.  And suppose further that the same control (call it "Button A") has different functions depending upon the mode.  Many documents, when talking about one mode will present the usage for both modes of Button A.  Then when it comes to describing the second mode they feel they had already told you everything about Button A, and say no more about it.

I suggest that you repeat the Button A information where it is relevant in the document.  In other words, present the operation of Button A once for the first mode, and repeat that information about Button A again for the second mode.  Don't scramble your explanations in order to prevent your having to repeat something in your document.

When showing the overall picture of the product (in the "Getting to Know Your …" section) you should label each item on the product and give references in your document where you describe the control.  This is what I call a “Visual Index.”  A Visual Index is a tool that your Reader can use to find the description (in the User Document) of a control that he/she sees on the product.  See our Course Flowchart as an example of a Visual Index.  You can click on most items in the Course Flowchart and see a full explanation of the item.

Extending our Button A example (which works in two modes, say "recording" and "playback") your diagram of the product must provide more information.  For the label of Button A, you would say something like:

Button A.  (When Recording page 5; during Playback page 9)

Repetition is not so bad.

 

 

 


Resources for Writing Great User Documents: http://www.greatuserdocs.com

(c) 2007 Igetitnow! Training, Inc.