Alexis AguilarandMiranda Limonczenko
add223d7b3
## Problem Two writing patterns came up while editing the Vercel Marketplace guide in #51630, and the style guide doesn't cover either one. - **References to a list:** When another sentence sits between a reference and its list, as in "start from these tabs. Each one opens a different page:", _these_ has nothing to point back to. Nothing in the style guide covers this. - **Order of UI instructions:** Nothing says whether an instruction names the location or the control first. "Click **Manage** next to Supabase" asks the reader to look for **Manage** before they know where it is. Resolves DOCS-1452. ## Solution `02-elements.md` gets a new rule for lists and an addition to the existing step guidance, each with a recommended and a not recommended example. - **Point forward to a list with _the following_** (under **Lists**): When another sentence sits between a reference and its list, use _the following_, which points forward. When the reference is directly before the list, _these_ works too. - **Location before the action** (under **Procedures**): The step guidance now says that a step can begin with a short location phrase followed by the imperative verb, and that when a step says where to act, the location comes first. The examples use _click_ for buttons, following the `click` and `select` entries in `WORD_LIST.md`. ## Review instructions 1. Open `apps/docs/style-guide/02-elements.md` in the **Files changed** tab. 2. Read **Point forward to a list with _the following_** under **Lists**, and confirm that the examples separate the two cases: a reference directly before the list, and one with a sentence in between. 3. Read the step guidance at the start of **Procedures**, and confirm that the examples agree with the `click` entry in `WORD_LIST.md`. ## Checklist Check all before review: - [x] I have read [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) - [x] If I wrote a new docs topic or edited an existing topic, I used the `/write-the-docs` or `/edit-the-docs` skill, which applies the docs [style guide](https://github.com/supabase/supabase/tree/master/apps/docs/style-guide) --------- Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io>
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