Advice on Technical Formatting

We use two fonts in our technical writing: a sans serif font that we call normal font, and a monospace (fixed-width) font that we call tech font.

The tech font makes technical terms stand out to the reader when they appear in and out of quoted code. In general, it is used for terms and programs as they appear behind the scenes (e.g., in code or a command line) and within the infrastructure of a system. Terms that use normal font are often only seen on user-friendly, front-end interfaces and in marketing materials. Here are examples of each font in use:

Normal Font	Tech Font
Titles of documents and file types Bishop Fox Security Style Guide, a PDF file	Full names of files and file extensions Security_Style_Guide.pdf, “a .exe file”
Error messages and security questions “Please enter a valid user ID.”	File paths server/web/directory/
Names of organizations, companies, teams, and vulnerabilities DEF CON, .NET, Tor, EternalBlue	Email addresses, usernames, and passwords [email protected], @bishopfox, SYSTEM, admin:admin, password1
Names of products and their versions Ethernet, Steam, Ubuntu 17.04	Domain names and hostnames bishopfox.com, DC01, EXAMPLENET
URIs, URNs, and URLs as clickable links https://www.bishopfox.com/resources/	References to URIs, URNs, and URLs data:, www.bishopfox.com/[variable]
Types of fields, headers, parameters, etc. data element, content-type header, the Forgot Password field	Names of fields, headers, parameters, etc. C: drive, X-Forwarded-For header, Secure flag, url parameter
Descriptions of groups or roles administrator, “role allowing read/write access”	Names of groups or roles Domain Admins, Enterprise Admins
Types of requests GET request, pull request, PUT request	Characters or elements from code “Disallow wildcards [ * ]”, “the getID() function”
Line numbers and ports by themselves “On line 42 of the code…”, port 80, port 443	IP addresses (with or without ports) 192.168.1.1, 192.168.1.1:80
Reference numbers, standards, and vuln IDs CVE-2014-6271, MS15-034, RFC 1149, 802.11r	Code excerpts <b>Hello World!</b> 3. Go to 1

Terms that use the tech font appear in that style everywhere in documents outside of headings (including bullet points and figure captions).

Bold Text

When writing about clickable elements, we follow the Microsoft Writing Style Guide (see Appendix B). We bold button names that the reader is meant to click. When writing about a feature with the same name as a button, capitalize it if applicable, but don’t bold it.

• Click Track Changes to show all your future changes in Word.
• The Track Changes feature allows users to keep track of all their edits in a document.
• After selecting the OK button, the user was redirected to the Home tab.

Within the word list in this style guide, bolding indicates terms that have their own entries.

Technical Names

In this guide, we highlight software and tool names with unintuitive capitalization, spelling, or formatting. However, as new tools are always being created, here is some general guidance around how to style this kind of technical name.

About Tech Font

Software names should usually be written in normal font, but the following exceptions require tech font for clarity:

• Operating system commands and other command-line tools that are styled in tech font in their official documentation

  Ex: chattr, sudo

• Lowercase names that look like regular words

  Ex: ping

About Capitalization

Maintain the software’s original capitalization to avoid any confusion.

• Avoid starting sentences with an all-lowercase name. If a sentence must start with a lowercase name, do not capitalize it.

• If a term can be used as both a name and a command, spelling and styling may vary, so check how it is used in the specific instance.

  Ex: Bash vs. bash, SCP vs. scp