Abbreviations
Unless an abbreviation is common, spell out the words of the abbreviation on the first use in an article or topic.
Note
In FAQ documents, treat every occurrence of a term as the first use (that is, spell out the term and show the abbreviation in parentheses on every occurrence).
Show the abbreviation in parentheses after the spelled-out term on the first appearance on the page.
Example
access control list (ACL)
Use the abbreviation on subsequent uses on the page.
If you introduce an abbreviation, use it; don't alternate between the abbreviation and the spelled-out term.
Use the
:abbr:role to embed the words as a hover option for the first mention of an abbreviation in a paragraph.:abbr:`ACL (access control list)` You may use
:abbr:role on every subsequent reference, if desired. You can't use this role within any other text formatting notation in reStructuredText. The abbreviation could also be defined within the toolchain as a source_constant or a substitution.Toolchain substitutions would be in the
conf.pyfor Sphinx / Giza-based repos andsnooty.tomlfor Snooty-based repos.Don't capitalize the spelled-out term unless it's a proper name or normally capitalized.
Example
You spell out AJAX as Asynchronous JavaScript and XML, but spell out ACL as access control list.
Use the following guidelines related to abbreviations.
Guideline | Use | Don't use |
|---|---|---|
Don't show both the spelled-out term and its abbreviation in a title or heading. In most cases, use the abbreviation in the title or heading and show the spelled-out term and its abbreviation on first use in the text. | Adding an ACL An access control list (ACL) allows access from an outside network into the ObjectRocket system. | Adding an access control list (ACL) An ACL allows access from an outside network into the ObjectRocket system. |
Use only established abbreviations. Don't create new ones. | hybrid cloud | HC |
Don't use abbreviated forms of MongoDB product names. However, if you think that a user might use an abbreviated name in a search, you can tag the document with the abbreviation. | Cloud Provider Snapshots | CPS |
If an abbreviation is used as part of a compound modifier, hyphenate it as you would a word. For more information, see Hyphens in compound modifiers. | 100-Mbps rate | 100 Mbps rate |
Don't surround abbreviations with quotation marks. | OS | "OS" |
Use periods only if the abbreviation normally has them (for example, etc., although this should not be used in MongoDB content) or could otherwise be misread as a word, such as in. (for inch). | FAQ | F.A.Q. |
Don't use an abbreviation as a verb. | Use FTP to copy the file to the server. | FTP the file to the server. |
Avoid using abbreviations in the possessive. Instead, treat the abbreviation as an adjective or put it in a prepositional phrase. | Type the DBA password. Type the password of the DBA. | Type the DBA's password. |
To form the plural of an abbreviation, except for a unit of measure, append a lowercase s without an apostrophe. For most abbreviations of units of measure, the singular and plural forms are the same (for example, 1 pt and 10 pt). If an acronym already represents a plural noun, don't add an s. | user IDs 10 mm FAQ | user ID's 10 mms FAQs |
For abbreviated units of measure, insert a space between the number and the abbreviation. Insert a hyphen if the phrase is a compound modifier. | 256 MB 100-GB drive | 256MB 100GB drive 100 GB drive |
Don't use Latin abbreviations or non-English words and phrases. For more information, see Avoid Obscure Non-English Words and Abbreviations. | for example | e.g. |
Abbreviations of Byte and Bit
Byte is abbreviated with an uppercase B. Bit is abbreviated with a lowercase b. For example, gigabyte is abbreviated as GB, and gigabit is abbreviated as Gb.
Abbreviate capacity when a number preceeds the unit.
Spell out the term when used on its own.
If you want to emphasize bit or byte, use the spelled-out term rather than or in addition to the abbreviation.
Examples |
|---|
When the host reads a page into memory larger than 100 MB, it displays this value rounded up to the nearest megabyte (MB) in the summary report. |
The unit of value for this alarm is megabits per second (Mbps). |
Common Abbreviations
A common abbreviation is either an industry-standard abbreviation or
one that is well known to your target audience. Following are some
common abbreviations in the computer industry. You don't need to spell
out these terms on first use, unless you think the abbreviation is
unfamiliar to your audience. If you use :abbr: roles, you can use
them on common terms as a subtle aid in user understanding.
|
|
|
|
|