[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Portion of our style guide (IBM) about glossaries
Create clear, concise glossary entries to make it easier for users to understand concepts. A glossary defines terms that are used in a product, set of products, or technology area.
A glossary entry consists of the following components:
â A glossary term
â One or more of each or both of the following items:
â A definition of the term, optionally followed by one or two explanatory sentences and aÂSee alsoÂreference that points to a related term or terms
â AÂSeeÂreference that points to a preferred synonym for that term or to the spelled-out version of an abbreviated term
If there is more than one item, each item is numbered.
A glossary term can be a noun (including an abbreviation), a verb, an adjective, or an adverb. A term can consist of multiple words, such asÂmaterialized query table.
Include the following types of terms in your glossary:
â Terms for concepts that are specific to your product or technology area.
â Industry-standard computing terms that have a special meaning in your product or technology area. For example,ÂcursorÂhas a meaning in relational database products that is different from the meaning of a cursor on a computer screen.
Do not include the following types of terms in your glossary:
â Names of reference elements, such as commands, SQL statements, and error codes.
â Names of files and directories.
â Product names, in either spelled-out or abbreviated form.
â Generally, industry-standard computing terms with standard meanings. For example, do not defineÂmouseÂin a glossary for computer-literate users. You might want to include standard terms with standard meanings if you are writing for novice users. You can also provide a link to a standard computing dictionary or terminology website at the beginning of your glossary.
In addition, do not include a term in the glossary unless you use it in at least a few places in your documentation, such as in different topics or chapters. If you use a term only once or twice, especially close together, consider explaining the term where you use it so that users do not have to look it up in a glossary.
In the glossary, specify your selected terms as follows:
â Use an initial lowercase letter unless the term normally starts with an uppercase letter.
â Use the singular form of a noun unless the noun is always plural.
â Use the infinitive form of a verb withoutÂto.
A glossary definition consists of a sentence fragment that uniquely identifies a concept. You can optionally follow the definition with one or two sentences of explanatory information.
Write the sentence fragment as follows:
â Optionally, start with aÂuse label, which is an introductory phrase that identifies the context to which the definition applies.
Do not use a use label in the following cases:
â If the context is obvious. For example, in a single-product glossary, starting definitions with a use label that identifies the product creates unnecessary wordiness.
â If the use label incorrectly implies that a definition is specific to a product or technology. In addition to introducing a technical error, such use labels prevent sharing of definitions for common concepts across multiple products or technology areas.
â Define the term by using a part of speech that matches the part of speech of the term. The following table provides wording for terms that belong to different parts of speech.
Follow these additional guidelines for glossary definitions:
â Limit the definition to the information that is essential for defining the concept and distinguishing it from other concepts. If you provide one or two additional sentences, provide only information that is helpful for understanding the concept. Do not include task or reference information in a glossary entry.
â Do not use the wordÂyouÂorÂyour; glossary entries must not be user oriented. Use passive voice or refer toÂthe userÂinstead.
â Do not embed the definition of one term within the definition or additional explanation of a different term; instead, create separate definitions.
â Do not combine multiple definitions for the same term in a single paragraph. Instead, start each definition on a new line, and number each definition.
â Ensure that the definition is not essentially a repetition of the term.
â Do not create a definition that contains the term or a form of the term that you are defining, which is a type of circular definition.
To show the relationships between terms, useÂSeeÂreferences andÂSee alsoÂreferences.
UseÂSeeÂreferences in the following cases:
â To link synonyms, such as a deprecated term and a currently used term. Choose one term as the preferred synonym. For the nonpreferred term, provide aÂSeeÂreference to the preferred term; do not provide a definition. For the preferred term, provide a definition; do not provide aÂSeeÂreference to the nonpreferred term.
Do not include the wordÂsynonymÂin the entry for the nonpreferred term.
Do not create aÂSeeÂreference that results in a circular definition. You cannot use a term that has aÂSeeÂreference in the definition of the preferred term.
â To point users from the abbreviation for a term to the spelled-out term. For the abbreviation, provide aÂSeeÂreference to the spelled-out term; do not provide a definition. For the spelled-out term, provide a definition; do not provide aÂSeeÂreference to the abbreviation. Put the abbreviated term in parentheses after the spelled-out term.
UseÂSee alsoÂreferences to link terms that are related but not synonyms. SpecifyÂSee alsoÂreferences as follows:
â Place theÂSee alsoÂreference after the definition of the term and any explanatory sentences.
â Ensure that theÂSee alsoÂreferences are reciprocal: if term A has aÂSee alsoÂreference to term B, term B must have aÂSee alsoÂreference to term A.
â If there is a list ofÂSee alsoÂreferences, separate eachÂSee alsoÂreference with a comma, and end the list with a period. Do not use a conjunction before the finalÂSee alsoÂreference.
Examples of situations in which to useÂSee alsoÂreferences are as follows:
â To link opposite terms
â To link broader and narrower terms
Do not use aÂSee alsoÂand aÂSeeÂreference in the same glossary entry. Include aÂSee alsoÂreference only in the entry for the preferred term.
Exercise caution when referring to the glossary from other information:
â Do not index glossary terms.
â Do not link to other information from the glossary, other than to a standard computing dictionary or terminology website at the beginning of the glossary.
â Do not use an italic font for a term in the body of a document only because the term is defined in the glossary. Use an italic font for a term in the body of a document only if you explain the term in that location.
Arrange the glossary entries in alphabetic order. Unless your authoring tool imposes a different standard, use the letter-by-letter method, rather than the word-by-word method. The differences between the methods are illustrated in the following lists:
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]