Writing Guidelines

Focus Your Message. There should be a single primary message or point you’re trying to communicate and supporting information for that message or point. It is also helpful if you write with a single reader in mind. This makes it easier to focus your language and message.

Be concise. Avoid unnecessary modifiers. Use short words and sentences. Watch for run-on sentences.

Be consistent. If you start out by writing in past tense or the 3rd person, maintain the tense and / or point of view throughout. Here’s a quick list of tenses with examples:

  • First person, I, Me, My: Use to write from your own personal experience.
  • Second person, You, Your: This is used to imply that the reader is a character in the article, this can be used in instructional writing.
  • Third person, She/He/It/They: This POV is used when you are not part of the story and are sharing information as a third party. For inclusion and simplicity, the singular they should be used when the subject’s gender is unspecified or unknown. For example, “When a user logs in, they should always remember to…”

Write With Intention

Make sure your sentences are clear!

Avoid sales language. Write how you would speak. Don’t use jargon and marketing-speak. Avoid the overuse of acronyms (more on this later).

Use the Chicago Manual of Style. If you’re curious whether or not you should use a serial comma, or if something is capitalized, check the Chicago Manual of Style.

Proofread. And then proofread again. In addition to proofreading your draft at least two times, be sure to spell check and use a tool like Grammarly to check your work before publishing it. Note: Grammarly is not perfect. Review any suggestions and verify they are correct before accepting the changes.

Writing Rules

Proper Grammar. Proper grammar is the key to effective writing! When in doubt, refer to these guidelines or a source like Grammar Girl for grammar rules. If you want to brush up on English grammar, these are some great books to keep close by when you’re writing:

  • Eats, Shoots & Leaves
  • The Grammar Devotional
  • Strunk and White, the Elements of Style

Use Active Voice

In using an active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it. For example, “The dog chased the ball” vs. “The ball was chased by the dog.”

  • Words like “was” and “by” may indicate that you’re writing in a passive voice. Scan for these words and rework sentences where they appear.
  • Avoid adverbs / verbs that end in -ly.
  • Watch for overused adjectives like “very” “slowly” “important” “interesting” etc.

Abbreviations

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

  • First use: Network Operations Center (NOC); 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 and don’t worry about spelling it out.

Common Spellings / Formats

Pay attention to letter capitalization, use of periods, etc.

  • DTC (direct-to-consumer)
  • B2B
  • SaaS

Capitalization

Subject lines or headlines should use title case, but everything else should use sentence case. When using sentence case, the only words that should be capitalized in the middle of a sentence are proper nouns.

  • This is an Example of a Headline in Title Case
  • This is a subheading in sentence case
  • This is a subheading, but with a comma in the middle

There are specific title case rules where some words like prepositions, articles, and short conjunctions aren’t capitalized. It’s hard to remember all of them, so refer here if you’re unsure.

Numbers

There are quite a few rules here, but they’re pretty simple to remember.

  • Spell out a number when it begins a sentence.
  • In most cases, spell out all numbers up to ten.
  • Amounts over a million can be abbreviated: $150 million, 1.2 million
  • Abbreviate large numbers up to 1 million if there are space restraints, as in a tweet or a chart: 1k, 150M, 2,5B. If not, write them out: 1,000, 150,000.
  • Numbers over 3 digits get commas: 999; 1,000; 150,000
  • “Percent” should be written out unless the piece is focused on data, then the symbol (%) should be used.
  • Ordinal numbers like 1st and first can be used either way.

Here are some examples:

  • I ate three donuts at our weekly Water Cooler meeting.
  • Ten new employees started on Monday, and 12 start next week.
  • 11 percent of the profits are equal to $160,000.
  • I won $10 million in the lottery and 1st place in the ninth annual company marathon.

Punctuation Rules

Commas

When writing a list, use the serial comma (also known as the Oxford comma).

Yes: David is inviting his parents, Oprah, and George Clooney to dinner.

No: David is inviting his parents, Oprah and George Clooney to dinner.

For general comma use, use common sense. If you’re unsure, read the sentence out loud. Where you find yourself taking a breath, use a comma.

Hyphenation

Compound Nouns

When writing out new, original, or unusual compound nouns, writers should hyphenate whenever doing so avoids confusion. Example: call-to-action.

Compound Adjectives

Hyphenate two or more words when they come before a noun they modify and act as a single idea.

  • Example: off-campus apartment
  • When a compound adjective follows a noun, a hyphen is usually not necessary. Example: The apartment is off campus.

Hyphens

Use a hyphen (-) without spaces on either side to link words into a single phrase, or to indicate a span or range.

Examples:

  • first-time user
  • Monday-Friday

Em Dash

  • Use a true em dash, not a hyphen (-) or double hyphen (–)
  • Em dash shortcut: Option + Shift + Dash (-)
  • For non-digital communications, use an em dash without spaces on either side to offset an aside. Example: Salesforce Team Onboarding—one of our three service offerings—is now available to all clients.
  • For digital communications, add a space on either side of the em dash to avoid strange word breaks. Example: Sean thought Dawn was the donut thief, but he was wrong — it was Brian.