Glossaries
On this page
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
MongoDB-specific terms that apply to only one service
MongoDB-specific terms that are general or apply to many different services
MongoDB-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 MongoDB service works. However, don't include terms that are well-known or common (such as browser and blog). In the definition, describe how MongoDB 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 MongoDB glossary should contain mainly MongoDB terms. If the user could find the meaning outside of a MongoDB 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 MongoDB 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.