mirror of
https://github.com/supabase/supabase.git
synced 2026-10-06 18:05:11 +03:00
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>
65 lines
3.3 KiB
Markdown
65 lines
3.3 KiB
Markdown
# 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](../CONTRIBUTING.md#write-the-docs-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`](./WORD_LIST.md) | Terminology, spelling, capitalization |
|
|
| [`01-voice-and-tone.md`](./01-voice-and-tone.md) | Person, tense, sentence length, brevity |
|
|
| [`02-elements.md`](./02-elements.md) | Admonitions, code blocks, procedures, tabs, images |
|
|
| [`03-page-structure.md`](./03-page-structure.md) | Document type, section grouping, chunking |
|
|
|
|
## Before you open a pull request
|
|
|
|
Always run [`WORD_LIST.md`](./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 example
|
|
> `03-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](https://merriam-webster.com)
|
|
- For accessible writing, see [Google's accessibility guidance](https://developers.google.com/style/accessibility)
|
|
- For gaps, see [Google developer documentation style guide](https://developers.google.com/style)
|
|
- For an additional developer guide reference, see [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
|