Skip to content

Style guide: added list of acronyms that don't need to be spelled out #826

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 16, 2025
Merged

Style guide: added list of acronyms that don't need to be spelled out #826

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c3ecbee
added list of acronyms that don't need to be spelled out
travisamartin Jul 16, 2025
f4bdd1c
Added CPU, GPU, and RAM
travisamartin Jul 16, 2025
00ad2ca
Added JSON, FQDN, PEM, YAML, and CIDR
travisamartin Jul 16, 2025
c7eb2cc
docs: update N1 config sync steps for v3 (#825)
JTorreG Jul 16, 2025
ee68491
Merge remote-tracking branch 'origin/main' into style-guide-acronyms-…
travisamartin Jul 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 37 additions & 8 deletions documentation/style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,6 @@ The table provides guidelines about the terms you should and should not use for
| cookie/cookies (noun) | | |
| covers | As in, "this section/topic/chapter covers the following...". Instead, use a phrase such as, "This topic deals with..." or "This topic provides the following information...". More options: communicates, presents, offers, introduces, explains, describes. | |
| curly brackets `{}` | The name for the curved `{}` parenthetical markings is "braces". They are not called curly brackets. | |
| CVSS v3.0 | Do not spell out. (Articles with CVSS metrics should include the CVSS link.) | |
| daemon | Avoid using this term in generic documentation because it is UNIX-oriented. Instead, we use "agent", "utility", or "application". However, we do refer to specific UNIX daemons, like `named` and `sod`, when daemon is part of the name. | |
| data center | Write this as two words. | |
| domain name | example.com, example.net, example.org, or localhost per [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606.html). | |
Expand Down Expand Up @@ -147,7 +146,6 @@ The table provides guidelines about the terms you should and should not use for
| Forwarding (IP) | See virtual server types. | |
| Forwarding (Layer 2) | See virtual server types. | |
| forwards | Use backward and forward, not backwards and forwards. | |
| FTP | Do not spell out. | |
| fu, fubar | Do not use; always replace with specific text. Watch for these in code samples. | |
| future releases and TBD | Do not use TBD in any content, including release notes. Do not reference future releases, such as This OID will be disabled in future releases. | |
| G | Abbreviation for "giga", but in computer terminology represents 230, or 1,073,741,824. Correct: 4G | |
Expand Down Expand Up @@ -190,7 +188,7 @@ The table provides guidelines about the terms you should and should not use for
| IPv4-in-IPv6 vs. IPv4 in IPv6 | You can hyphenate IPv4-in-IPv6 when used as an adjective, such as IPv4-in-IPv6 tunnels. Note that the internal v in IPv4 and IPv6 should remain in lowercase format. | |
| ISO 9001:2015 certification | For example: ISO 9001:2015 certified" or ISO 9001:2015 certification Don't use: ISO certified or ISO certification (Per: ISO - Certification, for questions about the use of ISO Certificate terms and logo, please contact the GS quality team at *qmt) | |
| it | Avoid ambiguous pronouns. Be explicit: "Check the status of the server. Restart ~~it~~ the server" | |
| jargon | Jargon is the technical terminology or characteristic idiom of a special activity or group. Try hard to avoid it. Think about explaining something to a member of your family or a friend who doesn't know what you know. F5 products are highly technical, but strive to be as plainspoken as possible when describing or instructing. Spell out abbreviations on first use, use the clearest and easiest word to understand that will still accomplish the job, and so on. | |
| jargon | Jargon is technical language used by people in a specific group or field. Avoid it whenever you can. Imagine you’re explaining the topic to a friend or family member who doesn’t know the technology. F5 products are technical, but your writing should still be clear and simple. Spell out acronyms the first time you use them. Use words that are easy to understand and still get the job done. For exceptions, see the [Acronyms](#acronyms) section. | |
| JWT license file | Include the word "license" when referring to the JSON Web Token that users download as part of their F5 NGINX subscription. | |
| kill | Avoid this term except in command line syntax, where it is a UNIX command for stopping processes. (It's actually an IEEE POSIX standard command.) Alternatives for describing the action are: § End the process § Interrupt the process § Quit the process § Shut down the process § Stop the process | |
| known issue | Abbreviate as "KI" when using in public-facing documentation. | |
Expand Down Expand Up @@ -296,8 +294,6 @@ The table provides guidelines about the terms you should and should not use for
| space | Do not use when referring to an input field or checkbox where the user needs to enter info. Recast to identify as a box. | |
| SPDY | Correct: a SPDY profile (pronounced speedy). | |
| spin up/spin down, spinning up/spinning down | Jargon, but becoming more widely used because of AWS. Do not use in our documentation without adding context on first reference. For example You can spin up (create additional virtual instances) or spin down (remove virtual instances) . . . . | |
| SSH | Do not spell out. | |
| SSL | Do not spell out. | |
| SSLi/SSL Intercept | For the SSL Intercept iRule. Spell out. Do not abbreviate except to match UI label. | |
| Sync-Failover (and Sync-Only) | Title capitalize and hyphenate to Sync-Failover unless referencing the option in tmsh; then lowercase and hyphenate as sync-failover. These guidelines apply to Sync-Only as well. | |
| tap | Describes action of touching the hardware touchscreens in hardware documentation. Do not use in software documentation; use "select" instead. | |
Expand All @@ -314,7 +310,6 @@ The table provides guidelines about the terms you should and should not use for
| Traffic Management Microkernel (TMM) | First mention: the Traffic Management Microkernel (TMM)Subsequent references: the TMM | |
| Traffic Management Operating System (TMOS) | Do not use. See TMOS. | |
| typically vs. normally | When describing a predictable and expected action in technical content, write in terms of what is typical rather than normal for clarity. Normal implies judgment. Avoid particularly when applying to user actions, practices, or behaviors. Use typical instead. | |
| UDP | User Datagram Protocol. Do not spell out. | |
| UI/GUI/WebGUI | Don't use these terms in documentation. For UI, call it the browser interface or user interface if necessary. Don't use GUI, or WebGUI. | |
| unsecure and non-secure | Use unsecure and not insecure when describing a lack of security regarding something technical or technology-related in our documentation. If preferred and internally consistent with what you are documenting, non-secure may be OK, but defer to your editor. | |
| update | Use when moving from one minor version of a product to another. For example, from NGINX Instance Manager 2.1 to 2.2. For example: Before updating your system, you should read the release notes to understand any new issues. For example: OIDC-authenticated users can't view the Users list after updating to NGINX Instance Manager 2.9.1. | |
Expand All @@ -328,8 +323,6 @@ The table provides guidelines about the terms you should and should not use for
| virtual address | Use instead of virtual IP address or VIP. | |
| virtual address vs. virtual IP address | Although this refers to the IP address part of a virtual server destination address, only use virtual address (which also reflects the GUI). | |
| virtual edition/Virtual Edition | Use virtual edition as a generic term. For Virtual Edition, see VE. | |
| Virtual Local Area Network (VLAN) | Do not spell out unless necessary to context. | |
| Virtual Private Network (VPN) | Do not spell out unless necessary to context. | |
| walk | Don't use. Anthropomorphism. Instead, try guides, leads, conducts, directs, shows… Example: The Setup utility guides you through a series of pages. | |
| warning/caution | Caution is less severe than Warning. Use Caution when alerting that damage may occur, such as data loss. Use Warning as the severest form of advisory, reserved for when there's a hazard to personnel (such as you're being directed to install a server rack and there's a chance it may fall on you). | |
| wget | command.| |
Expand All @@ -345,6 +338,42 @@ The table provides guidelines about the terms you should and should not use for
| Wizard and wizard | When documenting the GUI, you can capitalize Wizard if appropriate, such as for the Network Access Setup Wizard. When writing about wizards in general, or when a page title of a dialog box or GUI does not show Wizard in uppercase format, you can leave wizard in lowercase format. | |
| WWW or www | Do not include www. in web addresses In text, do not use WWW, but use Internet instead. Of course, you can use www as part of a URL. Although we're moving away from that, too. | |

## Acronyms

The following acronyms do not need to be spelled out:

| Acronym | Definition |
|---------|------------|
| API | Application Programming Interface |
| CIDR | Classless Inter-Domain Routing |
| CPU | Central Processing Unit |
| CVE | Common Vulnerabilities and Exposures |
| CVSS | Common Vulnerability Scoring System |
| DHCP | Dynamic Host Configuration Protocol |
| DNS | Domain Name System |
| FQDN | Fully Qualified Domain Name |
| FTP | File Transfer Protocol |
| GPU | Graphics Processing Unit |
| gRPC | gRPC Remote Procedure Call |
| HTTP | Hypertext Transfer Protocol |
| HTTPS | Hypertext Transfer Protocol Secure |
| IP | Internet Protocol |
| JSON | JavaScript Object Notation |
| JWT | JSON Web Token |
| NAT | Network Address Translation |
| PEM | Privacy Enhanced Mail (file format) |
| RAM | Random Access Memory |
| SMTP | Simple Mail Transfer Protocol |
| SSH | Secure Shell |
| SSL | Secure Sockets Layer |
| TCP | Transmission Control Protocol |
| TLS | Transport Layer Security |
| UDP | User Datagram Protocol |
| VLAN | Virtual Local Area Network |
| VPN | Virtual Private Network |
| WAF | Web Application Firewall |
| YAML | YAML Ain't Markup Language |


## Topic types and templates

Expand Down