Si vous n'êtes pas à l'aise avec l'anglais, utilisez ceci :
Cet outil vous fournit une traduction automatisée en français.
Great Technical Writing Improve Document Searches
OVERVIEW
Searches in User Documents (manuals, etc.) often fail because the Reader uses different words for a concept than the author uses. Since the Reader's words do not appear in the document, the document search mechanism cannot find them, resulting in frustration. This article describes a User-friendly technique for improving searches, without having to change the Users' behavior or the search software.
YOUR READERS' WORDS
People use the words that they know when they speak, write, or search. It's folly to try to force the Reader to use the writer's terminology; the Reader simply might not know the "proper" term. Forced to use unknown words, the Reader will find the User Document to be arrogant, or at least difficult to use.
For example, a User Manual for a word processing program will probably use the word "formatting" when dealing with character fonts and size, as well as page layout. But suppose that your Reader uses the word "appearance" to refer to these topics. How can we get the search mechanism to provide the correct result if the Reader searches for "appearance"?
THE TECHNICAL ANSWER: A THESAURUS SEARCH
The technical solution would be to convert the document search software from being an "exact term" search to a "Thesaurus Search." In a Thesaurus Search, the User enters a word that he/she knows, and the search returns synonyms or references to the synonyms in the document. Thus a properly set up Thesaurus Search should return references to "formatting" if the Reader searches for "appearance."
Unfortunately, the Thesaurus Search is rarely available, and creating one would require changes to the existing search program. A low tech solution may be the best answer.
THE ANSWER: SYNONYMS
For this technique, you need to put synonyms of the author's word ("formatting") on the pages that you want the search to find. Such synonyms may include "appearance," "design," and "layout." This is a simple, effective solution.
You can find appropriate synonyms by using the thesaurus that is a component of most word processors and of many libraries. Select the synonyms that your Readers are likely to use. "Likely to use" is based on your analysis of your Reader.
This leads us to the next question: How do you put the synonyms on the page?
DON'T USE HIDDEN TEXT
Technically savvy writers may ask "why not use hidden text for the synonyms?" The benefit is that hidden text will not "clutter up" the page.
So, if in the sections of the User Document where "formatting" is presented, the writer put the word "appearance" as hidden text (assuming the search utility would find this hidden information), then the following will happen:
1. The Reader searches for "appearance."
2. The search takes the Reader to the "formatting" section of the document.
3. The Reader wonders "How did I get here?" The word that he/she searched for ("appearance") does not appear on the page, since it is hidden.
Given that a goal of a User Document is to answer the Reader's questions, then doing anything that causes him/her to ask another question ("How did I get here?") is counter-productive. Hidden synonyms are not the best answer.
THE ELEGANT SOLUTION: "YOU MAY KNOW THIS AS..."
Hiding the synonyms is not a good idea. It's better to let the Reader know what's going on. The easiest way is to add a line of text on the page where the topic appears. This line of text begins with the phrase, "You may know this as..."
To continue our "formatting" example, our explanatory synonym phrase becomes, "You may know this as appearance, layout, or design." A search for "appearance" brings the Reader to the "Formatting" section.
Upon seeing the phrase "You may know this as appearance, layout, or design," the Reader knows why the search found this location. The search satisfied the Reader, and did not add uncertainty to the situation.
THE BOTTOM LINE
The goal of all good User Documents is to improve the Reader's experience with the product. By using synonyms for "technical" terms, the writer makes the Reader's document searches more effective, since the needed topics will be found using the Reader's words.
By not hiding the synonyms, the Reader is not confused as to why he/she arrived at that place in the document. The result is a better experience with the document and the product.
BONUS : Great Technical Writing: Improve Your Readers' Access With A Visual Index
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
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.
