> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation style guide

> Style guide covering tone of voice, capitalization, numbers, links, images, headings, and lists for SuperOffice documentation.

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][1] (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][2].

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.

* Don't use emojis in technical content except in forum discussions.
* Don't use constructions like he/she. If you struggle with pronouns, use [Microsoft's tips for bias-free communication][3].

## 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.

## Links

* 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][4].
* 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.

[1]: https://docs.microsoft.com/en-us/style-guide/welcome/

[2]: https://ahdictionary.com/

[3]: https://docs.microsoft.com/en-us/style-guide/bias-free-communication

[4]: https://docs.microsoft.com/en-us/style-guide/scannable-content/lists