Grammar & Mechanics

Adhering to certain rules of grammar and mechanics helps us keep our writing clear and consistent.


Read for all readers. Some people will read every word you write. Others will just skim. Help everyone read better by grouping related ideas together and using descriptive headers and subheaders.

Focus your message. Create a hierarchy of information. Lead with the main point or the most important content, in sentences, paragraphs, sections, and pages.

Be concise. Use short words and sentences. Avoid unnecessary modifiers.

Be specific. Avoid vague language. Cut the fluff.

Be consistent. Stick to the copy patterns and style points outlined in this guide.


Abbreviations and acronyms

If there’s a chance your reader won’t recognize an abbreviation or acronym, spell it out the first time you mention it. Then use the short version for all other references. If the abbreviation isn’t clearly related to the full version, specify in parentheses.

  • First use: Network Operations Center

  • Second use: NOC

  • First use: Coordinated Universal Time (UTC)

  • Second use: UTC

If the abbreviation or acronym is well known, like API or HTML, use it instead (and don’t worry about spelling it out).

Active voice

Use active voice. Avoid passive voice.

In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.

  • Yes: Marti logged into the account.

  • No: The account was logged into by Marti.

Words like “was” and “by” may indicate that you’re writing in passive voice. Scan for these words and rework sentences where they appear.

One exception is when you want to specifically emphasize the action over the subject. In some cases, this is fine.

  • Your account was flagged by our Abuse team.


Article/Knowledge Titles

We employ a modified Title case. Read the Title Capitalization page for details.

Email Addresses

When writing out an email address or website URL, use all lowercase.



Don't capitalize random words in the middle of sentences.

  • website

  • internet

  • online

  • email

Visit the Links page for requirements, writing, and implementation details.

Last updated