mirror of
https://github.com/supabase/supabase.git
synced 2026-10-18 23:59:08 +03:00
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:
1 parent
8f1e65f0a3
commit
add223d7b3
1 file changed
+17
-2
@@ -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).
|
||||
|
||||
Reference in new issue
Block a user