Great Technical Writing Improve Document Searches

Great Technical Writing Improve Document Searches


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.


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 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.


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?


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.


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 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.

Great Technical Writing Improve Document Searches

Related Posts:

No comments: Comments Links DoFollow

Powered by Blogger.