tekom-Jahrestagung 2012 - ActiveDoc

Professionelles Schreiben / Technical Authoring
Classification
The Definition
Statement
The Example
Acronyms and
Initializations
Best practices
A good definition is made of up these elements:
The classification is the first thing that points the reader’s mind in
the right direction. For example, a classification for “chair” might be
“furniture.”
This is the short (one or two sentence) actual definition. It cannot be too
broad (for example, if I say that a chair is a type of furniture that you
can sit on, I am accidentally including things that aren’t chairs, such
as sofas). It cannot be too narrow (for example, if I say that a chair has
arms, I am accidentally excluding all the chairs that don’t have arms).
The trick is to find the elements that capture the essence of this object
or concept.
The example helps the reader understand the definition. I like to think
of it as the “aha! factor.” In some cases, an example may be a wellknown
instance of the concept (for example, if I was defining DTP, I
might mention Microsoft Word as an example, because many people
recognize it, even if they hadn’t previously been familiar with the concept
of DTP). It may be a picture (this works well for definitions of
physical things). It may be a well-known use case. When choosing an
example, ask yourself, “Will this make sense to my reader?”
When defining any shortened form, always include the spell-out after
the term, in parentheses. For example:
−−
DTP (desktop publishing): a software application that…
Conclusion
A good set of definitions, in a central, easily-accessible location (glossary
chapter in a print document or a glossary tab in online Help, for example),
can add value to your documentation and improve user loyalty.
If you have any questions please contact: leah@cowtc.com
436
tekom-Jahrestagung 2012