Essay Online

OVERVIEW

People are visual creatures. They look at your product, and see, for example, a button or display. They want to find out about that control or indicator. A Visual Index is a simple but powerful document access tool that enables your Readers to find the information that they want.

This article describes the Visual Index concept and tells how to create one for your document.

A VISUAL INDEX

A Visual Index is a picture of your product or process with links to the relevant information in the related document. Using a Visual Index, your Readers can look at the picture, and quickly jump to the place in your document that describes the item of interest.

Your document may include several Visual Indexes (the plural of “index’ is “indexes” not “indices”).

STARTS WITH A PICTURE

The Visual Index starts with a picture of your product or process. There are various kinds of pictures to use, based on the product type:

* Physical Product (for example, a barbecue or video disk recorder)

Pictures of the product (all relevant views).

* A Procedure or Process: A flowchart of the steps and decisions in the procedure or process.

* Software Product 1: Screenshots of the software.

* Software Product 2: Before and after images of the work that the product does.

* Organization: An organization chart.

LABEL THE PICTURE

Label all the User-Product Interaction Points (U-PIP) on the picture. A U-PIP is anywhere that your User and the product may interact. U-PIP’s include controls, displays, and relevant physical features of the product (such as handles, latches, etc.). Provide a meaningful (to your Reader) label (name) for the U-PIP. (Use that same exact label everywhere you refer to that U-PIP.)

Aside: If your product uses sounds to inform the User, then include a table of those sounds, what they mean, and a link into the relevant area of your document (describing the sound).

LINK THE U-PIP’s TO YOUR DOCUMENT

Up to this point, the Visual Index is just like any well-labeled picture of your product or process. However, when you add links into your document, the well-labeled picture becomes a Visual Index.

The link should be to a section of your document that you believe your reader would most want to reach to get the information about that U-PIP. (This is a fundamental question whenever you create an index: “does my reader want to come to this place in my document for this item?”)

Your method of adding links to the picture depends upon the publishing mechanism for the document. If the document is published as:

* A Printed document, then use page numbers for the links;

* An Electronic Document, then use hyperlinks that a Reader can click on to follow. If the document is published as HTML, then the visual index can be an image map.

EXAMPLE 1: A PAIN IN MY FOOT

I have a pain in my foot when I walk. If I go to a website about feet, it would be very efficient for finding out about my pain, if I could see a picture of a foot with various areas where the pain could be. Links from the foot areas to specific web pages would enable me to find the information about my specific foot pain quickly.

EXAMPLE 2: PHOTO CORRECTING SOFTWARE

Show a picture with the errors that your software can handle, before and after correction. Here the U-PIP’s are each of the photo errors.

EXAMPLE 3: A COURSE ON WRITING USER DOCUMENTATION

The Visual Index is a flowchart for creating the User Document. Since the Course is presented in HTML, the Visual Index is made from an image map, with hyperlinks into the sections of the Course relevant to each item in the flowchart.

BOTTOM LINE

A Visual Index is a simple concept. But like many simple concepts it is very powerful. Try to include one in your next document. You’ll be doing your Reader a great service.

OVERVIEW

For small companies, creating their product’s User Documentation in-house, provides benefits to the company, to (idle) staff, and to the product. This article describes the benefits and some downsides of producing User Documents in-house.

THREE OPTIONS

If you have no in-house writing staff you have three options:

1. No User Document for the product. This is NOT a valid option. Every product needs User Documentation. It completes your product package, and enhances the User’s experience with your product. Here are two examples of non-existent User Documentation:

* Tomatoes. Most people don’t know that before use, tomatoes should not be refrigerated. Refrigerating tomatoes before use will reduce their flavor and nutrition value.

* A Manual Can Opener. This can opener clamps on the can, thus the user does not have to squeeze the handles while operating the can opener. It came with no User Documentation, as “everyone could probably figure out how to use it.” This is wrong. After a few uses, the blades become slightly dulled, and the handles are very difficult to clamp and lock.

The simple tip of turning the knob while squeezing the handles makes the can opener easy to use. That tip could form the basis of a User Manual for the product. The manual should include instructions for care of the can opener. The absurd situation is that this clamp feature was the unique aspect of the product; but the feature becomes unusable because of no User Document.

How have you felt about products that came without User Documentation? Were you confused about the product and getting the most from it? User Documentation adds to the value of the product. Let’s look at how we can get it created.

2. Use an outside writing service or consultant. Technical writers may be an excellent choice to create your User Documentation. However, there may be downsides to using them.

* When documentation changes have to be made, the company has to re-hire the writer. If the writer were unavailable, then you have to wait or search for a new writer. When the new writer gets hired, a new orientation to the company and the project would have to start. Delays, delays, delays.

* An even more horrible thought is that the outside writer used some fancy piece of software to create the User Document, and you do not own that software. Thus you could not make any changes until you bought and learned that software, or hired an outside writer who uses the same software. (Most technical writers are enamored with a particular piece of esoteric writing software.)

Using the outside writer will force you to batch your documentation changes, making the literature out of date. (How many times have you seen product documentation that does not match the product? This happens because the company was waiting for the next major upgrade to update the User Documentation.)

3. Using idle employees in your company to create the User Documentation. The remainder of this article will focus on this option.

STAFFING BENEFITS

In most organizations, there is some staff down-time. By assigning these staff to create User Documents you benefit from effective use of this down-time, and the employees benefit from experience in a new field.

These staffing benefits include:

* Use staff who may be idle between projects

* Your staff know the company’s culture and their fellow staff

* Your staff use existing company-wide writing tools (your word processor)

* No time needed to get oriented with the physical aspects of the job

* You have created a new resource within company

BENEFITS TO YOUR USER DOCUMENTS

If you have in-house writers (even if they are not formally trained as “technical writers”) you can just say “Sue, could you or Tom update the document where the sign-in window is presented.” Much faster and more flexible then having to go to an outside source. Sue and Tom have ownership of the document, and would work to improve it. They would use software resources available in your organization.

The benefits of in-house writers to your User Documents include:

* You can make corrections as you find the errors.

* You are able to update your User Document when you update your product.

* Better control of timing and resources

* No fear in dealing with the User Document in electronic form. From your word processor or add-ins, you can publish your User Document as a portable data format (.pdf) file, or as HTML for display on the Internet.

DOWNSIDES OF IN-HOUSE WRITING

The primary downsides of in-house User Document creation are the attitude and emotions of your newly-appointed writer. These include:

* Fear (”I don’t know how to write”)

* Anger (”Why me? This is unfair”)

* Uncertainty (”I don’t know what to write”)

* Isolation (”I’ve been cast into this writing thing”)

You can reduce these negative emotions if you encourage and support your New Writer.

SUPPORT YOUR NEW WRITERS

It is unfair to assign a non-writer to create a User Document without supporting him/her. You have to support your writer with:

* Training;

* Access to the development and marketing teams for product information;

* Use of the development team to evaluate their writing (small chunks);

* Access to the product, industry literature, and marketing materials;

* Style manual;

* Editor — your writing expert;

* Time to do a good job.

Other articles in this series (see the links in the “Resources” or “About the Author” section of this article) present more information about supporting your New Writer.

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.