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:
18.191.212.246