Miranda Limonczenko
4b15c67f4a
The word list names Google as its only source, which reads as a single point of reference. List the Microsoft guide alongside it.
Supabase documentation style guide
Welcome to the documentation style guide. This is a living document that serves as the evolving source of truth for:
- Our Supabase voice and our audience
- The structure of our technical documents
- How we consistently talk about our product
This guide is for everyone who is writing to help Supabase users. It can be used by anyone who writes for Supabase, no matter your role or whether you are an employee or open source contributor.
The style guide is also for both humans and LLMs: our SKILLS use the style guide, but the style guide is also human-readable and friendly. Much of this guide is dedicated to removing AI smells such as verbosity and overused asides.
We encourage you to contribute to the style guide so that we write the best documentation for Supabase. If something consistently bothers you, it may bother others as well. That could be an inconsistently used term or an unnecessarily verbose writing pattern. Open a style guide PR and start the discussion.
Navigation
The files in the style guide are numbered in the order of content size. It starts with
the smallest piece, at the word level, then progresses to the sentence, the element,
and the whole page. WORD_LIST is unnumbered and a master document for our word
consistency decisions.
| File | Covers |
|---|---|
WORD_LIST.md |
Terminology, spelling, capitalization |
01-voice-and-tone.md |
Person, tense, sentence length, brevity |
02-elements.md |
Admonitions, code blocks, procedures, tabs, images |
03-page-structure.md |
Document type, section grouping, chunking |
Before you open a pull request
Always run WORD_LIST.md against the finished page. We removed any
linter and instead entrust you to use the word list.
You can run /review-the-docs for a local self-review, and /test-the-docs if the page
contains runnable snippets.
If you drafted with an agent
Run a critic pass. Open a subagent with a clean context, holding only the relevant guide files and the draft text, and give it this instruction:
Referencing the docs style guide, cite every rule violation in the draft. Quote the offending phrase and cite the rule it breaks as
file#anchor, for example03-page-structure.md#chunking. Derive the anchor from the heading itself, and ignore headings inside fenced code blocks, which are examples rather than rules. Then resolve.
Each citation has to resolve to a real heading in the guide. One that doesn't is an invented rule, so check the citations before you act on them.
References
- For spelling, see Merriam-Webster.com
- For accessible writing, see Google's accessibility guidance
- For gaps, see Google developer documentation style guide
- For an additional developer guide reference, see Microsoft Writing Style Guide