Miranda Limonczenko
a5688423d0
Closes DOCS-1320 Was the bottom of a two-PR stack. The commit from #50680 moved here, so that PR is closed and this one carries both changes. ## Problem The CLI getting started guide had accumulated structural and prose problems, none of which change what the page claims: - **Nine flat H2 headings**, with Beta channel and Updating the Supabase CLI sitting between installing and running. A first-time reader crossed about 150 lines of beta and upgrade tabs before reaching `supabase init`. - **The introduction opened with a two-step procedure under no heading**, listing `init` and `start` before the CLI is installed. Its first sentence named the tool and where it runs rather than what the reader gets. - **Running a local Supabase project ran concept, fact, procedure, and process together** as one stretch of prose, so the two commands the reader has to run sat in paragraphs between the Docker background and the first-run note. - **Task headings mixed gerunds with imperatives:** Installing, Running, Stopping, and Updating next to Access and Manage. - **No navigation.** A long guide that mixes information types opened straight into commands, with no outline of its major groups. The sidebar contents is not a substitute: it isn't part of the document, and the generated markdown an agent reads has no sidebar at all. - **Four more sequences were prose.** Installing via npm, installing a Linux package, the pre-upgrade backup, and opting out of telemetry each had to be followed in order with nothing marking the order. - **Smaller things:** the Studio screenshot's alt text named the topic its heading already states, two links used "note above" and "here" as their text, and an admonition restated where `sb_publishable_...` comes from. ## Solution Twelve commits, one change type each, plus a master merge and its fixup. - **Style.** The install-method callout drops from four blocks to two paragraphs and uses the documented `title` prop. Active voice on the Postgres, analytics, and telemetry instructions. Descriptive link text. Alt text that describes the Studio screenshot rather than naming it. Cut the admonition restating `sb_publishable_...`. - **Structure.** Beta channel and Updating the Supabase CLI move out of the getting started path. - **Grouping.** Local setup goes under Set up a local project, updating and beta builds under Change your CLI version. The intro's `init` and `start` list gets a Quickstart heading. - **Value statement.** The opening sentence now says what the reader gets. - **Procedure format.** Running a local Supabase project leads with the container runtime prerequisite, then four numbered actions, then the first-run download as an outcome. Starting the container runtime is its own step, since the old prose only assumed it with "with a container runtime running". - **Imperative headings.** Install, Run, Access, Stop, Update, Use the beta channel. - **Four more procedures.** npm install, Linux packages, the pre-upgrade backup, and telemetry opt-out. The three pre-upgrade commands were one unexplained block inside an admonition, so each step now says what its command does. Re-enabling telemetry moves to a sentence, since it's the reverse action rather than a step. - **Intro navigation** listing the major groups, each line saying what the reader gets from it. - **Connect to a hosted project** (from #50680). A new section between Stop local services and Change your CLI version, saying the stack runs only on the reader's machine and nothing reaches a hosted project until they sign in and link one, then pointing at the page that owns the procedure. No commands. The `init` step gains a sentence saying it creates local files only, and the value statement and intro navigation cover the added goal. - **Style guide and word list fixes** from an audit of the page against `CONTRIBUTING.md` and `WORD_LIST.md`. `directory` over `folder` in command-line contexts, `might` over `may`, present tense over `will`, a noun after `this`, no `above` as a pointer, concrete verbs over `manage`, no time-relative `latest`, no parentheses for supplementary information, and an impact-first `caution` on the pre-upgrade callout. The container runtime list becomes a table of tool and platforms, and the group heading becomes Change your CLI version. ## Preview links | Site | Live | Preview | Search for | | ---- | ---- | ------- | ---------- | | Docs | [/docs/guides/local-development/cli/getting-started](https://supabase.com/docs/guides/local-development/cli/getting-started) | [/docs/guides/local-development/cli/getting-started](https://docs-git-docs-cli-getting-started-edits-supabase.vercel.app/docs/guides/local-development/cli/getting-started) | Change your CLI version, Connect to a hosted project | ## Manual testing 1. Open the docs preview link above. 2. Read the introduction. It opens with a value statement, then links the four major groups. Under Quickstart, the install-method callout explains how the install method changes the command you run. 3. Read the On this page list. It nests: Quickstart, Set up a local project with four sections under it, Change your CLI version with two sections under it, Telemetry, Learn more. 4. Check Run a local Supabase project renders four numbered steps, with code blocks inside steps 3 and 4. Check the npm tab of Install the Supabase CLI renders three, and How to opt out renders two. 5. Load the page at `#installing-the-supabase-cli`, `#beta-channel`, and `#updating-the-supabase-cli`. All three land on their sections despite the renamed headings. 6. Load the legacy path `/docs/guides/cli/getting-started#updating-the-supabase-cli`. It redirects to the current path and keeps the fragment. 7. Check the introduction's group list includes Connect to a hosted project, and that the section appears in the On this page list between Stop local services and Change your CLI version. 8. Check that section is two sentences and a pointer, with no commands. 9. In Run a local Supabase project, select the "Connect to a hosted project" link in step 3. The page scrolls to that section. 10. Follow both outbound links from the new section and confirm they resolve, including the `#configure-github-actions` fragment. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Reorganized the local development guide with a clearer quickstart, setup steps, service access instructions, and CLI version guidance. * Expanded installation examples to include bun and clarified package-runner commands. * Clarified upgrade, backup, container cleanup, and telemetry instructions. * Added a reference to the Microsoft Writing Style Guide. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
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