This chapter explains how to create a glossary for a technical manual. Most technical manuals increasingly introduce a number of new terms. A glossary improves the usability of a technical manual by simplifying a reader’s search for definitions for these new terms. Before you create a glossary, consider its use and organization.
This chapter discusses the following topics:
“Glossary Content” on page 231
“Terms for an International Audience” on page 233
“When to Include a Glossary” on page 234
“Writing Good Glossary Entries” on page 234
The terms that you select for a glossary must be important to the subject, with simple and concise definitions that are appropriate for the context. A glossary can contain some background definitions that are not defined within your book if these definitions enhance understanding of the subject. An example is units of measure.
A glossary can also include terms that have another meaning apart from technology. Examples are “front porch” and “portal.” You might also include terms that are unique to the book.
Some terms are not considered appropriate for a glossary. These terms include the following:
Commands from a programming language or from an operating system
Window menu selections
Terms that a reader can find in a standard dictionary or an industry glossary
For terms that are specific to your particular product, try to obtain definitions from your technical subject matter expert, usually an engineer. For standard industry terms, first check a standard dictionary. If the term is not in this dictionary, check the third-party reference books that are listed in Appendix B.
Online glossaries are usually easy to access. You might find the definition that you need without much difficulty.
Note
Note — If you need to borrow definitions from another source, ensure that you rewrite the definitions so that you are not guilty of plagiarism. To inspire originality, define a term as if you were creating a definition for someone who is unfamiliar with the term or technology.
Ensure that your glossary is verified in a technical review, along with your main text.
If you need to create an entirely new term for a name in a new product, follow these guidelines:
Ensure that the new term can be pronounced as you intend.
If you have any doubts, use a different term. An example is “invalid,” which can be pronounced two ways with two different meanings.
Ensure that the new term cannot be read as obscene and that the term’s meaning cannot be mistaken.
Ensure that a translator can adequately translate the new term.
Glossary page formats differ from book to book. You can see these differences especially in Internet glossaries, which use a variety of publishing software for their online presence. All glossaries do have some common characteristics:
All terms are arranged alphabetically.
Each term begins on a separate line.
Each term is followed by its definition or expansion.
Some glossaries capitalize the first letter of each important word in an entry. Other glossaries capitalize only proper nouns in terms. Examples in this chapter follow the correct capitalization of the term as used in the book. Terms often follow the capitalization that is recognized by a standards organization, such as ANSI, IEEE, or ISO. The typeface, margins, and indents are determined by the templates and the publishing software that you use to create the glossary.
If your document or documentation set has a glossary, ensure that the language of definitions in the text is consistent with that glossary. If you are working with a translation or localization group, provide a glossary and a style sheet for your document.
When you are writing glossary definitions, remember the concerns of translators and nonnative speakers. This audience sometimes struggles to understand a new term in English in the process of rewording the term in another language. Therefore, be as complete as possible when you write a glossary entry. Try to include the following items:
Grammatical use in a sentence, when a distinction is important
For example, is the term a plural noun that is more commonly used in English as a singular noun?
Source, location, and usage of the term
For example, where is the term used: in software, a graphical user interface, help files, hardware, marketing material, web navigation, or legal documents?
Sample sentence that shows the term’s usage (optional)
In many instances, the term is so widely used that the particulars do not need to be carefully defined. But the value of the glossary increases as you add details for the international audience. For more information about internationalization, see Chapter 7.
If you are documenting new technology, a glossary is almost mandatory. An audience that is unfamiliar with the topic can probably benefit from a major set of definitions.
To decide whether you need a glossary for your book, consider your content. If your content describes a new product with many new vocabulary words that you define within the text, include a glossary.
Alternatively, if the scope of your content does not extend to new material, you might not need a glossary. If you do not need to define many terms as you write, your audience might be familiar with the terminology.
If your book is a legacy book that has never had a glossary, add a glossary if you have time. The inclusion of a glossary especially applies to books that are undergoing major revisions. If you define many new terms within the text, you need to create a book glossary.
Ideally, you define each new term at least three times:
At its first usage in text
Give a brief but concise definition of the term.
At its first usage in a subsequent chapter if the book is hard copy only
Here, a short, summary definition suffices.
In the glossary
Users expect a complete definition in the glossary.
The best time to write a glossary entry is when you first introduce an unfamiliar term in your text.
When you write text, you frequently need to introduce terms to your audience. Define new terms and technical terms that are not listed in a standard dictionary the first time that those terms occur in text. Italicize terms when you first define them. Also, include these terms in a glossary. For example:
Several configuration files are included with your package. A configuration file is a text-readable file that is used to set up or configure a part of the system.
The use of italic indicates that an entry for the word “configuration” appears in the glossary.
Note
Tip — Some authoring environments for online presentation enable you to link a definition directly to the italicized term.
configuration | (1) (n.) The way that you have set up your computer. |
(2) (n.) The combination of hardware components that compose a computer system: CPU, monitor, keyboard, and peripheral devices. | |
(3) (n.) The software settings that enable various hardware components of a computer system to communicate. |
Glossary style usually presents the glossary term in a simple, singular noun form. The part of speech that you use for the term demands that you use the same part of speech as a keyword in the definition. An example follows.
concatenate | (v.) To string together two or more sequences, such as files, into one longer sequence. |
node | (n.) An addressable point on a network. Each node in a network has a different name. A node can connect a computing system, a terminal, or various other peripheral devices to the network. |
The definition, which immediately follows the term, does not restate the term. The restatement might be assumed, along with the unwritten words “is a” or “is,” if the article is included. An example follows.
debugger | (n.) A program that locates operational errors in another program. The debugger usually enables the developer to examine the malfunctioning portion of the program for bad data and to check operational conditions. See also debug. |
decryption | (n.) The process of converting encrypted data to plain text. See also encryption. |
Ensure that the definition agrees in number with the term. The definition does not need to be a complete sentence.
Defining a term that consists of multiple words, usually one or more modifiers and a noun, is similar to defining a single word. An example follows.
shell procedure | (n.) An executable file that is not a compiled program. A shell procedure calls a shell to read and execute commands that are contained in a file. This procedure enables you to store a sequence of commands in a file for reuse. Also called a shell program or command file. |
Of all glossary users, translators and nonnative speakers can benefit the most from knowing the part of speech for a term. However, all users can improve their understanding of a term by knowing how to use that term in a sentence. The following list shows the abbreviations for parts of speech.
adj. | Adjective |
adv. | Adverb |
n. | Noun |
v. | Verb |
The following example shows two parts of speech:
format | (1) (n.) The structure of data that is to be processed, recorded, or displayed. |
(2) (v.) To put data into a structure or to divide a disk into sectors for receiving data. |
When a term requires more than one definition, use a numeral that is surrounded by a set of parentheses and no other punctuation. Append a space to this text. Start a new paragraph for each definition, as the following example shows.
luminance | (1) (n.) The generic flux from a light-emitting or light-reflecting surface. The subjective response to luminance is brightness. |
(2) (n.) The specific ratio of color primaries that provides a match for the white point in a specified color space. | |
(3) (n.) The portion of a composite signal that carries brightness information. |
Acronyms and abbreviations are alphabetized letter-by-letter, as described in “Alphabetizing a Glossary” on page 238. Occasionally, you need only give an expansion of the term. At other times, you need to provide a definition as well.
Because most users are familiar with just the acronym or abbreviation, spell out the meaning and give the definition immediately after the acronym or abbreviation. You can double-post the abbreviation and the expansion. The following examples show entries with abbreviations and expansions.
SIP | (single inline package) (n.) The packaging of an electronic component with all leads protruding from one side only. |
SMPTE | (n.) Society of Motion Picture and Television Engineers. |
SNMP | (Simple Network Management Protocol) (n.) The preferred network management protocol for TCP/IP-based internets. |
When you use multiple definitions for an acronym or abbreviation, use a numbering system, as the following example shows.
BSD | (1. Berkeley Software Distribution) (n.) UNIX versions that were developed at the University of California, Berkeley. These versions have names such as BSD 2.7 and BSD 4.2. |
(2. block schematic diagram) (n.) A circuit board flowchart. |
When you refer to another term, use the word “See” to direct the reader to use another word. Do not define the term when you use “See.”
solid model | (n.) See surface model. |
Use “See also” after you have defined a term to direct the reader to other terms with similar meanings. If you are referring to an acronym or abbreviation, use the short form. The following examples show two ways to use “See also.”
composite drive | (n.) A single logical drive that is composed of more than one physical drive. See also disk array, RAID. |
| (n.) A file that lists commands which are to be executed at specified times on specified dates. See also |
The writer is responsible for arranging a glossary alphabetically. Most publishing software does not automatically alphabetize a glossary. Most glossaries are alphabetized by the letter-by-letter method. This method does not observe spaces between words. An example follows.
typefaces
type form
typescript
type size
For online use, your glossary definition can contain multiple online links. These links reduce the number of “See also” citations. In the example that follows, a set of underscores indicates online links. These links are not displayed as sets of underscores in online text.
namespace table | (n.) The place where all _namespace_ information is stored, for use by the _classing engine_ as well as a _namespace manager_. Each namespace table consists of entries (rows) and each entry consists of a set of named attributes. |
For more information about online writing style, see Chapter 4.
Do not index the glossary. Because the glossary is arranged alphabetically or searched by keyword, a reader can find any definition quickly, with no need for index entries.
However, a reader might look for a glossary term in the index to determine how the term is used in the main text of the document. Consequently, some terms that are in the glossary might also appear in the index. These index entries should cite only pages that are in the main text.