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).