Documentation style guide

• 3 minutes to read
 • 3 minutes to read

This style guide is intended to ensure that SuperOffice documentation is clear, has a consistent style, and is easy to find, easy to use, and easy to understand.

Adopting these guidelines also limits variation, thereby eliminating confusion, guesswork, and debates.

General notes

We adopt the Microsoft Writing Style Guide (formerly MSTP) as our primary style guide and use standard US English spelling with serial (Oxford) comma. If you’re stuck or unsure, look it up in the American Heritage Dictionary.

Entice scanners with subheadings, bulleted lists, and whitespace.

Omit needless words

Use simple words and short sentences. This is not the same as dumbing down your content.

  • Use strong, active verbs.
  • Write in 2nd person, present tense.

Capitalization

Use sentence case capitalization!

  • Capitalize all proper nouns, also in headings.
  • Never capitalize website, internet, online, and email within a sentence.
  • Put functionality names in lower case.

Tone of voice

SuperOffice’s voice is personal. It’s honest, it’s friendly, and it’s straightforward. Our priority is to be valuable and helpful to our readers and users.

Do’s and don’ts

  • Always spell out SuperOffice.
  • Use bold or italic text for emphasis. Don't use uppercase for emphasis.
  • Use 1 space after sentences.

Abbreviations, acronyms, and contractions

  • Spell out acronyms and abbreviations on 1st occurrence except if it is well known.
  • Use contractions except if the content will be translated.
  • Don’t use Latin abbreviations.

Numbers and symbols

We use a 24-hour clock and metric units of measurement.

  • Spell out numbers starting a sentence; otherwise use numerals or ordinals.
  • Hyphenate ranges.
  • Spell out percent; don’t use the % symbol.
  • Don’t use blind links or raw URLs.

Images

  • Always use alt text!
  • Don’t change file names added or delivered by Marketing.
  • Capture screenshots at the highest resolution available.

Headings

  • Use sentence case.
  • Keep the heading as short as possible.
  • Write your headings unique and extremely specific.
  • Frontload keywords, especially in content with an SEO focus.

Lists

Lists are 1 of the most powerful constructions when it comes to presenting clear, scannable content. Reserve numbered lists for step-by-step instructions and sequences where order matters.

  • Don’t put extra space between list items.
  • Use parallel construction.
  • If at least one list item is a complete sentence, capitalize the first letter and add a terminal punctuation mark to all list items. Otherwise, omit the terminal punctuation mark and don’t capitalize the first letter (unless it is a proper noun).

Documenting code and UI

  • Refer to methods either as doSomething() or as the doSomething function.
  • Put UI elements and interaction in bold. Don’t use quotes.