Glossaries#

Create a glossary to document the following items:

  • New, unfamiliar, or unique terms

  • Familiar terms used in a new or special way

  • Abbreviations or acronyms that should be clarified

This section provides guidelines for the following items:

For guidelines about formatting glossary terms that are used in regular text, see Text formatting.

Glossary terms#

To show the glossary term that you’re defining, use the following guidelines:

  • Use the singular form unless the term is always plural. For example, use server instead of servers.

  • Use lowercase letters unless the term is a proper noun or acronym. For example, use server instead of Server.

  • If the term has an acronym or abbreviation, show the term either in its spelled-out form or shortened form, depending on which term is more familiar to users. If you use the spelled-out form, follow it with the abbreviation in parentheses.

To alphabetize glossary terms, use the word-by-word method. In this method, terms that contain more than one word separated by spaces or commas are alphabetized by the first word only, unless the first word of two or more entries is the same. In that case, the second and subsequent words are used to determine the alphabetical order. Hyphens, slashes, and apostrophes continue a single word.

Example word-by-word alphabetization

new math

newborn

new/old

newspaper

Glossary definitions#

Make your glossary definitions brief. Try to restrict definitions to no more than one or two short paragraphs, and avoid the inclusion of notes or tips. If your definition is longer than one or two short paragraphs, it might be more appropriate as a concept in an overview section rather than in a glossary.

Begin the definition with a descriptive phrase. Capitalize the first letter of the phrase, and end the phrase with a period. Follow the initial phrase with one or more sentences as needed.

How you begin the definition also depends on what part of speech the term is:

  • Noun: Begin with the appropriate article (a, an, or the) and a noun phrase.

  • Verb: Begin with the infinitive form of another verb that defines the term.

  • Adjective: Begin with a verb such as describes or pertains to.

  • Abbreviation: Begin with the spelled-out term.

The following table shows examples.

Note

In a comprehensive glossary, you might need to start the definition with a qualifier that identifies the service to which the term relates. For more information, see Guidelines for a comprehensive glossary.

Type

Example

Noun

token

An opaque string that represents an authorization to access cloud resources. Tokens might be revoked at any time and are valid for a finite duration.

Verb

resize

To convert an existing server to a different flavor, in essence, scaling the server up or down. The original server is saved for a period of time to allow rollback if a problem occurs.

Adjective

RESTful

Describes a kind of web service API that uses REST.

Abbreviation

API

Application Programming Interface. A set of commands, functions, and protocols that programmers can use to create application services by using an open application.

Cross-references to glossary terms#

Use the following guidelines when creating cross-references within a glossary:

  • For a term with a definition located under a different entry, use a See entry in place of the definition.

  • For a term with a definition that’s related to, is similar to, or contrasts with another term, refer to the term in one of the following ways. If that term actually occurs in the definition, you can simply link to its definition from the term. If the term doesn’t occur in the definition, add a See also entry at the end of the definition.

    Tip: To highlight a difference between two terms, you can use a Contrast with entry.

  • Format the cross-reference as follows:

    • If using a See or See also reference, type See or See also, and apply italics. If you’re referring to more than one item, italicize and.

    • Make the term a link to the cross-referenced term.

Examples

address

See address space.

collection

A group of packages that have the same qualifier.

data point

A value that stores metrics. Metrics are stored as full resolution data points, which are periodically rolled up (condensed) into coarser data points. See also data granularity.

replace

To recover by dropping the selected database and re-creating it. Contrast with copy over.

Guidelines for a comprehensive glossary#

A comprehensive glossary might have the following types of terms:

  • Industry-standard terms

  • Third-party product terms

  • Rackspace-specific terms that apply to only one service

  • Rackspace-specific terms that are general or apply to many different services

  • Rackspace-specific terms that apply to two or more services and have different meanings for two or more services

Following are guidelines for how to handle each type of term in the comprehensive glossary:

  • Include industry-standard terms only if they’re integral to understanding how a Rackspace service works. However, don’t include terms that are well-known or common (such as browser and blog). In the definition, describe how Rackspace incorporates the idea represented by the term, or which service employs it. For example, API.

  • Avoid including third-party terms. Within the documentation itself, provide links to third-party websites if you want to provide more information about third-party terms. A Rackspace glossary should contain mainly Rackspace terms. If the user could find the meaning outside of a Rackspace document by using a browser search, then we probably don’t need to include it in the glossary. For example, Apache.

  • If a term is specific to one Rackspace service, start the definition with the name of that service in parentheses, and italicize it.

  • If a term is general or applies to many different services, you do not need to qualify it.

  • If a term is specific to more than one service but has a different meaning for each service, provide all the relevant definitions in one glossary entry. Place each definition in a separate paragraph and start the definition with the service name, in parentheses and italicized.