Language & Grammar I: Abbreviations & Acronyms#
Abbreviations and Acronyms are used to shorten phrases and words which are pronounced as the word itself. Many developers and documentation writers prefer to use abbreviations and acronyms while defining ideas and processes. While defining abbreviations and acronyms is defined by the documentation hierarchy, we have some standard sets and rules for the same:
Avoid using abbreviations and acronyms in titles and headings.
Spell out the term if a particular abbreviation has been spelt out only once in the entire document.
Prefer using English terms over Latin abbreviations.
Avoid using English slang and prefer to use objective language over casual.
Acronyms like Exempli gratia (e.g.) and id est (i.e.), should be always followed by a comma.
Acronyms other than i.e. and e.g. should be capitalized.
Don’t abbreviate words like the developer (dev) or repository (repos) as they introduce colloquialism.
Don’t add an s for abbreviations of a plural noun or to indicate plurality.
Avoid using the possessive form of the word.
Connect with the Subject Matter Expert (SME) while deciding to put common abbreviations (like HTML or PDF) in the user documentation.
Recommended examples |
Not recommended examples |
---|---|
An element of Moja Global documentation repository. |
An ele of Moja Global docs repo. |
I don’t know why this file is missing. |
IDK why this file is missing. |