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 <miranda.limonczenko@supabase.io>
This commit is contained in:
Alexis AguilarandMiranda Limonczenko authored and GitHub committed 2026-10-16 09:07:04 -07:00
1 parent 8f1e65f0a3
commit add223d7b3
1 file changed
+17 -2
+17 -2
View File
@@ -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).