Getting in the Last Word - Part One - Glossary

When you’ve finished writing your procedures and organized them into a usable manual, do you throw your hands up signaling victory and dance a jig because you’re finished?

No, not yet.

You haven’t completed the most important parts of the manual: Index, Glossary, and FAQ (Frequently Asked Questions) sections.

What? You thought the most important parts of the manual were the procedures?

Well, tell me then; how can your users find the correct procedures if there isn’t a good index? Sure, they can flip helplessly through the pages, hoping to find the right procedure. Maybe, they’ll even happen upon it by reading the table of contents. However, I can assure you that before your user finds the procedure they need, they’ve thrown your manual up against the nearest wall and screamed in frustration.

I know. I’ve been there. And, I’ve seen other users do the exact same thing. For that reason, I refuse to write any procedure manual without including a comprehensive index, useable glossary, and user-friendly FAQ section.

Listed below, you’ll find a three part series of important Do’s and Don’ts for getting in the very best last words for Glossaries, Indexes, and FAQs.

Part One - Glossary

Do arrange glossaries in alphabetical order.

The best glossaries are those that are arranged alphabetically with numbers first then characters.

Don’t waste space trying to define every word in your technical manual.

It isn’t necessary to rewrite the dictionary. Stick to only those terms that are unfamiliar to the reader.

Do give the reader a definition that is easy to understand and doesn’t include a form or variation of the term.

Nothing is more frustrating than to read a glossary that uses the term in the definition.

Don’t include procedures in the Glossary.

Keep your definitions short and to the point. If a procedure is necessary, refer the reader to the appropriate section. Procedures should never be included in a glossary.

Do imbed definitions in the procedures for more difficult terms.

If the user must stop reading the procedure more than once to look up a definition, you lose the reader’s attention. For these terms, it helps to define them within the procedure.

Don’t build up the technical word count just for your own sake.

Keep the use of technical and words that may be new to the reader to a minimum.

Do define all terms or phrases with special meanings specific to the product or application.

Depending on the application, written procedures can contain terms or phrases that take on a specific meaning when used in that application.

Go To Page: 1 2