From add223d7b31ca0cd64b389f4367b618e20b001cb Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Fri, 16 Oct 2026 09:07:04 -0700 Subject: [PATCH] docs(style-guide): add rules for list lead-ins and UI instruction order (#51632) ## 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 --- apps/docs/style-guide/02-elements.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/apps/docs/style-guide/02-elements.md b/apps/docs/style-guide/02-elements.md index ea9085ba8f5..28e7b5868fe 100644 --- a/apps/docs/style-guide/02-elements.md +++ b/apps/docs/style-guide/02-elements.md @@ -146,6 +146,17 @@ Use an ordered list for steps taken in sequence, and an unordered list when orde doesn't matter. Use Arabic numerals (`1`, `2`, `3`) for ordered lists and dashes (`-`) for unordered lists. +#### Point forward to a list with _the following_ + +When a sentence refers to a list but another sentence sits between it and the list, use +_the following_. _These_ reads as pointing back at something already on the page, so the +reader can't tell which items it means. When the referring sentence is directly before +the list, either word works. + +- **Recommended**: `To open Supabase Studio, start from either of the following tabs. Each one opens a different page in Supabase:` +- **Recommended**: `Start from either of these tabs:` +- **Not recommended**: `To open Supabase Studio, start from either of these tabs. Each one opens a different page in Supabase:` + #### Prefer a paragraph to a single-item list A list of one signals content that was meant to grow and didn't. Exceptions: layout @@ -185,8 +196,12 @@ to need one. The format makes that expectation explicit. Write sequential actions as an ordered list. **Begin each step with an imperative verb, -and include one action or a closely related set of actions per step.** Give the reader -enough context to know where to act. +or with a short location phrase followed by one, and include one action or a closely +related set of actions per step.** When a step says where to act, put the location +first. Give the reader enough context to know where to act. + +- **Recommended**: `Next to Supabase, click **Manage**, then click **Open in Supabase**.` +- **Not recommended**: `Click **Manage** next to Supabase, then click **Open in Supabase**.` For how many steps to present at once and when to split a procedure into phases, see chunking in [`03-page-structure.md`](./03-page-structure.md).