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