tekom-Jahrestagung 2012 - ActiveDoc

Professionelles Schreiben / Technical Authoring
TA 21
Workshop
The purpose of
a definition
Adding Value through Glossaries
Leah Guren, Cow TC, Karmiel, Israel
The need for glossaries
Users are increasingly abandoning official product documentation in
favor of other sources, which are not controlled by the company and
may not be accurate. A main reason for this mass exodus is assumed
knowledge; that is, user frustration at terms and concepts that are not
explained.
By providing rich, value-added glossaries, we can make our documentation
more accessible, more appealing, and more useful to a wider range
of users. A good glossary provides these benefits:
−−
It supports the needs of different users. Users are never a completely
homogeneous group. A glossary can fill in knowledge gaps without
getting in the way of advanced users.
−−
It helps users learn. It serves as a handy, centralized location for
short, easy-to-consume pieces of information about the product and
domain.
−−
It showcases expertise. Each well-written definition underlines your
company’s expertise in the domain in a subtle yet effective way.
−−
It helps keep users loyal to your documentation. If users can understand
product terms and concepts within the product documentation,
they are less likely to go elsewhere to find answers.
A definition in product documentation it is not meant to explain every
detail; its real function is to give users enough of an understanding—the
context—to be able to continue using the documentation. Think of it as a
hook upon which users can then hang more information.
What should you include?
How do you know what you should define? Consider the following:
−−
Product terms. Think of product names, especially different flavors of
products and related products.
−−
Features. Users don’t always understand what feature names do. For
unusual features, include feature concepts (what the feature actually
does).
−−
Interface elements. Think about terminology used to discuss types of
interface elements. Do all of your users know what an “option button”
is?
−−
Workflow concepts. Are there terms that apply to your users’ workflow
but aren’t explicitly named in the interface? Does your company
use a term that may not be universally recognized in the industry?
−−
Actions (verbs with special use). Do you use special terms to describe
any user action?
−−
User groups or classes. Do you talk about group leaders or trainees or
associates or administrators?
−−
Domain concepts. Think of technical terms in the field, acronyms or
initializations, and even concepts.
−−
Any word that your company uses in a special way.
tekom-Jahrestagung 2012
435