## 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>
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>
