opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add What's next? carve-out to the Learn more style rule (#27163)

Browse Source 
## What

Adds a **What's next?** carve-out to the **Learn more, not Next steps**
rule in the docs style guide (`docs/.style/style-guide/word-choice.md`).

The existing `## Learn more, not Next steps` heading, its two
rationales, and the ban on **Next steps** are unchanged, so the
`#learn-more-not-next-steps` anchor is preserved. A new `### Sequenced
tutorials: What's next?` subsection lets a tutorial in an ordered series
point to the single next tutorial, and the enforcement note now
clarifies that the planned `Coder.LearnMore` rule flags **Next steps**,
not **What's next?**.

## Why

**What's next?** and **Learn more** do different jobs:

- **What's next?** carries the reader along a defined sequence: the
single next tutorial.
- **Learn more** stays optional related reading, such as feature or
reference pages.

The **What's next?** phrasing also avoids the "steps" mobility metaphor,
so the inclusive-language reason for banning **Next steps** still holds.

The merged Quickstart "Customize your template" series (#26712) already
uses **What's next?** sections, so this codifies the pattern those pages
adopted.

## Implementation plan and decision log

- Keep `## Learn more, not Next steps` (preserves the anchor and the
core ban).
- Add `### Sequenced tutorials: What's next?` after the Learn more
Do/Don't examples: a tutorial in an ordered series may add a **What's
next?** section pointing to the single next tutorial, placed above
**Learn more**, written as a short sentence with the link.
- Add a **Do** example showing **What's next?** above **Learn more**.
- Update the closing note to: *Enforced by `Coder.LearnMore` (planned).
The planned rule flags Next steps, not What's next?.*

Decisions:

- Subsection, not a new top-level rule, keeps the shared rationale and
the `#learn-more-not-next-steps` anchor intact.
- The planned Vale rule must flag **Next steps** but allow **What's
next?**, so the note calls that out explicitly to prevent a future false
positive.
- Diff scope: only the Learn more section changes (21 insertions, 1
deletion); no other rules are touched.

---
Generated by Coder Agents on behalf of @nickvigilante.
This commit is contained in:
Nick Vigilante
2026-07-23 16:21:40 -05:00
committed by GitHub
parent 66a55e1ebd
commit 5bafbace8e
1 changed files with 21 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.style/style-guide/word-choice.md
+21 -1
View File
@@ -216,7 +216,27 @@ Two rationales apply:
- [Set workspace autostart](./autostart.md)
```
*Enforced by `Coder.LearnMore` (planned).*
### Sequenced tutorials: What's next?
A tutorial in an ordered series may add a **What's next?** section that points to the single next tutorial in that series.
Place it above **Learn more**, and write it as a short sentence with the link.
**What's next?** is distinct from **Learn more**: it carries the reader along a defined sequence, while **Learn more** stays optional.
It also avoids the "steps" mobility metaphor, so the ban on **Next steps** still holds.
**Do**:
```markdown
## What's next?
Now that you added a language, [install your own command-line tools](./install-command-line-tools.md).
## Learn more
- [Parameters](../../admin/templates/extending-templates/parameters.md) in the Coder documentation
```
*Enforced by `Coder.LearnMore` (planned). The planned rule flags Next steps, not What's next?.*
## Tutorial, not walkthrough