Miranda LimonczenkoandNik Richers
8fa75be01b
Part 1 of 3. Stack: #50742 → #50744 → #50743. ## Problem We have several problems: - Style guidance lives in lots of places and need consolidation - Our CONTRIBUTING guide has turned into one massive style document that needs to be broken up ## Solution Add `apps/docs/style-guide/` as plain markdown. | File | Covers | | --- | --- | | `README.md` | What the guide covers, who it's for, how to contribute, and the references it defers to | | `WORD_LIST.md` | Terminology, spelling, capitalization, and the `agent` / `LLM` / `AI` distinction. Moved from `apps/docs/` with history intact | | `01-voice-and-tone.md` | Audience, brevity, sentence construction | | `02-elements.md` | Which component renders each piece, and linking conventions | | `03-page-structure.md` | Document types, information types, grouping, chunking, timeless documentation | ### New content This guide is mostly rearrangement and glue, but it includes some new content: - Links and cross-reference formatting - WORD_LIST entries for LLM and AI agent - Timeless documentation guidance - Accessibility guidance - Sharper guidance on brevity and chunking ## Manual testing 1. Open `apps/docs/style-guide/` on this branch and confirm `README.md` renders below the file list. 2. Follow every link in `README.md` and read the document through. 3. You can test by locally pointing an agent at the style-guide and seeing that it makes great choices when revising a document. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a documentation style guide covering voice and tone, page structure, and guidance for writing procedures, code, tables, diagrams, media, and links. * Added a word list with preferred spelling, capitalization, and usage, including guidance on inclusive and concise language. * Added recommendations for reviewing documentation drafts and runnable examples. * Replaced the existing word list page’s content with a link to its new location in the style guide. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Nik Richers <nik@validmind.ai>
3.3 KiB
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