TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
>******Melonie asked:******
>> Do yall tend to call out a term which is in the glossary
>> in some manner (such as bold or underline)? Does
>> anyone know if this helps or distracts the reader?
>>
>> Thanks,
>>
>> Melonie R. Holliman
>
>******Elizabeth replied:******
>I use a serif type for text, and sans-serif bold for the terms. I
>haven't heard that it's distracting.
>Elisabeth B. Zakes
>
>
>******Rebecca's addition******
>I tend to do essentially the same thing as Elizabeth, but only where (if
>any) the term is initially used or applied in the text. I don't do it
>everywhere the term appears -- I've found that by the end of the book, it
>looks like a ransom note if I do it more than just that first use.
>
>-Rebecca Merck
I usually italicize the first instance of a term, but only if it's defined
in that sentence or shortly thereafter. I don't italicize a term just
because it appears in the glossary. I italicize it to indicate that the
reader is not supposed to already understand the term, at least in the
specialized sense in which it's used in the document. Italicization tells
the reader, "this is not only a statement about the subject matter, it's a
statement about terminology." That's an important distinction.
I sometimes use bold instead of italics, since it makes it easy for a
reader to skip through the document looking for key terms. Terminology,
contra certain extreme-nominalist schools of thought in philosophy,
embodies some of the most fundamental knowledge, and a quick way to pick up
a new field is to learn its concepts.
However, bold sometimes makes the document "look like a ransom note" (great
description!). I would never use it in a (published) book, only in certain
kinds of technical documents. Also, in a lot of what I write, I'm already
using bold for something else. In requirements documents, I use bold
sans-serif for requirement statements and regular serif for body text,
including commentary and explanation that surrounds the requirement
statements. When I tried putting defining instances of terms even into
bold serif, the interaction between the two kinds of bold made the page a
mess.
I usually put quite a few terms into glossaries--many more than are defined
in the text. This is to help readers who don't have all the
industry-specific background knowledge of the primary intended readers or
who need their memories refreshed. To include these definitions of these
concepts in the main text would slow the document down and bore the primary
readers. I just toss them into the glossary as an added bonus (usually
pasted from some other document), and don't italicize them in the main text.
By the way, here are a few tips on writing both glossaries and definitions:
