# Documentation style guidance

We've defined some basic patterns to bring our documentation towards a more consistent, readable style. These also reflect our team's shared choices for communication overall.

- We are committed to inclusive communication
- We're a European organisation, and choose to use British English spelling (e.g., "organisation" not "organization", "centre" not "center"; we prefer "-ise" over "-ize" endings) 
- We use the Oxford comma
- We write dates as “January 1” or “January 1, 2025” format

Outside of specifically technical documentation sections that require particular terms (i.e. in prose, tutorials, and descriptive writing)

- We write in clear, accessible language that avoids jargon
- We use active voice and positive framing
- We keep sentences concise but helpful
- We avoid overly formal language 

## Terminology

Here is a non-exhaustive list of terms we use.

- we refer to "the Fediverse" as a collective noun
- "toot" is outdated (except in as a protocol extension); Mastodon statuses are posts, not toots
- "instance" is outdated, we prefer "server" over "website" or "instance" (except where instance is part of an API call or technical reference)

Example domains may be 
`mastodon.social`, `mastodon.online`, `example.com`, `example.social`

Always refer to other software by official spellings, and check for correct capitalisation, e.g.

- WebFinger (noun)
- ActivityPub (noun)
- ActivityStreams (noun)
- OAuth (noun)
- JavaScript (noun)
- OpenCollective (noun)

## Markup and styling

Consistency of terminology, punctuation, and formatting is important to us!

Code blocks should be correctly marked up with language hints (http, text, json, shell etc).
