From 5bafbace8ef488537c5b706b9f78d30ed692ce3f Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Thu, 23 Jul 2026 16:21:40 -0500 Subject: [PATCH] docs: add What's next? carve-out to the Learn more style rule (#27163) ## 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. --- docs/.style/style-guide/word-choice.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/.style/style-guide/word-choice.md b/docs/.style/style-guide/word-choice.md index d54ad2b787..15fc5eafa2 100644 --- a/docs/.style/style-guide/word-choice.md +++ b/docs/.style/style-guide/word-choice.md @@ -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