Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Join our discussions of documentation issues here on the blog and on Slack.
A shortened word or phrase which is part of the word or phrase, but condensed; sometimes with a period at the end.
Dr. – Doctor
Rd. – Road
etc. – et cetera
min – minutes
Sometimes the long and short versions of a word are used interchangeably. These words don’t need a period at the end.
max – Maximum
info – Information
app – Application
uni – University
Some words often have concurrent characteristics of acronyms, initialisms, or shortened words. Words like GUI, GIF could be either spoken as an acronym or an initialism; subject to preference of the speaker.
Spell out and declare abbreviations whenever they are used for the first time in a document. Avoid using abbreviations in titles and headings, unless absolutely necessary. If using an abbreviation in a heading/title is mandatory, spell out the abbreviation in the succeeding body text.
Upon successive mentions of the abbreviation in the document, you can use the abbreviation without spelling it out.
Consider your audience while defining or spelling-out an abbreviation. Some abbreviations like PC, RAM, USB, PDF are more well-known than their spelled-out terms. A developer demographic would be familiar with HTML, whereas a beginner or a general reader may not. In which case, it is up to you to decide whether a particular abbreviation needs to be spelled out. If you’re sure that your reader demographic is expected to understand the term, then you don’t need to spell it out.
Sometimes, readers may not understand that a Universal Serial Bus port might be a USB port. In these cases, not spelling out the word is preferred.
If an abbreviation appears only once in your document, just spell out the term. Don’t introduce it in parentheses after the spelled-out version. Use the most common form of the word/phrase. If the full word or phrase is most commons and understandable, use that rather than its abbreviation. For example, write approximately instead of approx.
Avoid internet slang abbreviations such as tbh (to be honest), fwiw (for what it’s worth), tl;dr (too long; didn’t read). Rephrase the sentence in an objective approach.
Use English terms over Latin abbreviations such as et al., eg., viz.; use and others, for example, namely instead of these.
Don’t add an s in abbreviations of measurements to indicate plurality. For example, 50 mi or 10 mm.
The article (a or an) that goes along with an abbreviation depends on whether the term is pronounced like an acronym or an initialism. For example, an API, an IDE, a URL, a CMS are the articles that go with these terms.
Lowercase all the words in the spelled-out form except for the proper nouns. Words like as, of, the, in abbreviations are rarely capitalized – sometimes not even included in the abbreviations. For example, NASA – National Aeronautics and Space Administration doesn’t include and in its abbreviation. On the contrary, the DOT – Department of Transportation includes an of in its abbreviation while also capitalizing it. Therefore, confirm the abbreviation and its spelled-out form for the concerned terms. Refer the Word list and usage dictionary for more information.
Use periods at the end of shortened words. Don’t use periods with acronyms and initialisms. Similarly, don’t use periods with commons words that are abbreviations such as app or demo. Don’t use a period with an abbreviation for the name of a country, US state, or the District of Columbia (DC).
The plural of an abbreviation can be formed like any other regular term; if the abbreviation is for a singular noun, add a lowercase s to form its plural. If the abbreviation is for a plural noun, don’t add an s. Examples include APIs, CMSs, IDEs. Also ensure that the possessive form of the word (an apostrophe ‘ before the s) is not used.