Skip to content

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

Draft
nickvigilante wants to merge 1 commit into
mainfrom
vigilante/docs-463-style-guide-add-a-whats-next-carve-out-to-the-learn-more
Draft

docs: add What's next? carve-out to the Learn more style rule#27163
nickvigilante wants to merge 1 commit into
mainfrom
vigilante/docs-463-style-guide-add-a-whats-next-carve-out-to-the-learn-more

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

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.

Keep the ## Learn more, not Next steps heading and ban, and add a
### Sequenced tutorials: What's next? subsection so ordered tutorials
can point to the single next tutorial in the series. Update the
enforcement note to clarify the planned rule flags Next steps, not
What's next?.
@linear-code

linear-code Bot commented Jul 10, 2026

Copy link
Copy Markdown

DOCS-463

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant