General Usage Guidance

How to Handle Acronyms

On the first reference, spell out the full term followed by the acronym or abbreviated version in parentheses. The spelled-out term that precedes the acronym should not be capitalized unless it is a proper noun.

Ex: cross-site scripting (XSS), Transport Layer Security (TLS)

If the term does not appear in this guide, follow the style used by a trusted source (see Appendix B).

Many entries in this guide advise whether to spell out an acronym or abbreviated term on first reference. These recommendations assume that the terms will be used in content for information security professionals. When this guide does not offer a recommendation or when terms are used in a different context, consider the following factors on whether to spell out:

• Readers may be more familiar with the acronym than the spelled-out form. Do not spell out in these cases except when you are actively defining the term.
  • Ex: ASCII, HTML, USB
• Decide whether spelling out the term helps to clarify the topic for the intended audience. If it does not, consider providing a brief explanation instead. For example, spelling out intrusion detection system (IDS) gives the reader an idea of what an IDS is. A term such as MITRE ATT&CK is better served by a brief definition.
• Context matters. For example, IP is short for either Internet Protocol or intellectual property. In a document that discusses both IP addresses and intellectual property, you will need to use your judgment.

How to Write Terms That Don’t Follow Our Style

If a client writes terms differently from our style, make a choice depending on the situation:

1. If it’s in a quoted code excerpt (including typos), leave it as is.
2. If directly referring to a product name or heading in the client’s environment, spell and capitalize it their way, as in E-mail Address. Sometimes we also put the term inside quotation marks to separate the client’s specific use from the generic term.
3. If we are referring to the generic term, we spell it our preferred way, as in email address. If examples in your code snippets or figures use the client’s spelling, check if the spelling difference might confuse the reader or might change the meaning. If you foresee a problem, talk to your editor.

If you prefer using more progressive or less common terms, mention the older variant on your first use so that your reader can find previous documentation on that topic.
Ex: Implement it through a primary/replica model (previously known as “master/slave”).