Skip to content

feat: enable Coder.StepLength Vale rule - #30791

Merged
nickvigilante merged 10 commits into
mainfrom
vigilante/docs-1272-style-guide-make-the-20-word-step-budget-a-limit-and-add
Oct 27, 2026
Merged

nickvigilante merged 10 commits into
mainfrom
vigilante/docs-1272-style-guide-make-the-20-word-step-budget-a-limit-and-add

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Adds Coder.StepLength, a Vale script rule for Keep steps short.
It flags an ordered-list step whose instruction, the step's first paragraph, has more than 20 words, counted as How to count words describes.
Paragraphs below the instruction explain the step and aren't counted.

  • Severity: warning.
  • Scope: docs/** except docs/.style/style-guide/**.
  • Baseline: 124 findings in 60 hand-written files.
    The cleanup shortens each long instruction, moves its explanation into one paragraph below it, or splits a step that holds several actions.
    After cleanup vale docs/ reports 0 Coder.StepLength findings, and the other rules report no new findings on the changed files.
  • The guide section now says the limit covers the instruction, and that one action or one explanation must not be broken across paragraphs to meet it.
  • Generated pages (docs/reference/{api,cli,agent-api}, configuration-reference.md, prometheus.md): no findings, so no .vale.ini exclusion is needed.

Linear: DOCS-1272

Decision log

Review change (Ian's review)

  • The first version limited every paragraph of a step to 20 words.
    The cleanup for it chopped explanations into several short paragraphs, which made steps harder to read and sometimes changed their meaning.
  • The rule now counts only the first paragraph segment of each step.
    The content files were reset to main and the cleanup was redone against the narrower rule.
  • Cleanup preferences, in order: shorten the instruction; keep a short instruction and put the explanation, with its original wording, in one paragraph below it; split a step into one step for each action; for descriptive lists (such as "How it works"), keep each item one statement.
  • docs/admin/users/oidc-auth/microsoft.md keeps the split into separate steps, with Ian's wording suggestions applied.
    "click" became "select" in step 16 because Coder.SelectClick flags it.

Rule shape

  • A script rule (Tengo) with scope: raw, because the count depends on Markdown structure that per-paragraph scopes hide.
  • A step is an ordered-list item with a 1. or 1) marker.
    A nested ordered item is its own step.
    Bullets, even under a step, are not steps.
  • The instruction ends at a blank line, a fence, a nested list, a table row, a blockquote, block-level HTML, or an explicit hard break (<br>, a trailing backslash, or two trailing spaces).
  • Fenced code blocks, HTML comments, tables, images, and nested bullets add no words.
  • CRLF: \r counts as whitespace, and offsets come from the raw text.

Counting approximations (also in the rule header)

  • A code span and a **bold** or __bold__ span are one word each.
  • Words split on whitespace, so a hyphenated compound and 30&nbsp;seconds are one word.
  • Link text counts word by word, destinations are skipped, images add no words, and <https://...> autolinks are one word.
  • A token with no letter or digit, such as the > in **A** > **B**, is not a word.
  • Tengo indexes strings by rune but measures them in bytes, so the script rewrites each non-ASCII rune to ASCII of the same byte length first.

Tests (fixtures under /tmp/sltest/, not committed; run with the repo .vale.ini, LF and CRLF)

  • Flagged: a long instruction, a short action and a long result in one paragraph, a long nested ordered step.
  • Not flagged: a long paragraph below a short instruction, text after a <br> hard break, a long paragraph after a code block, a long nested bullet.
  • LF and CRLF output is identical.
  • Pre-commit hooks (fmt/markdown, lint/markdown, lint/emdash, lint/style-claims, lint/typos) pass.
  • Not run on Windows or macOS.
    The rule is plain text processing, and the CRLF cases simulate Windows line endings on Linux.

Generated by Coder Agents on behalf of @nickvigilante.

Add the style rules from the Docs style guide Linear project that the
guide was missing, and fix the guide's own self-violations from the
second ASD-STE100 audit. Each new Vale rule lands in its own PR based
on this one, so every footer for those rules is marked planned.

The Vale doctrine now lets suggestion-level rules land with existing
findings, per Nick's decision on DOCS-450.

Refs DOCS-1282, DOCS-1265
@nickvigilante
nickvigilante force-pushed the vigilante/docs-1272-style-guide-make-the-20-word-step-budget-a-limit-and-add branch from 0f650a2 to e566290 Compare October 14, 2026 20:58
@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

DOCS-1272

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@nickvigilante
nickvigilante force-pushed the vigilante/docs-1272-style-guide-make-the-20-word-step-budget-a-limit-and-add branch from e566290 to 987e4af Compare October 14, 2026 21:28
Base automatically changed from vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide to main October 16, 2026 13:53
Take main's text for the conflicted pages, which main had reflowed to
one sentence per line, and reapply the step-length fixes on top of it.
Also shorten the one new over-limit step in the parameters
compatibility-mode page and recount the style guide's checks table with
the new row.

Assisted-by: AI
@nickvigilante nickvigilante changed the title feat(docs): enable Coder.StepLength Vale rule feat: enable Coder.StepLength Vale rule Oct 23, 2026
@nickvigilante
nickvigilante marked this pull request as ready for review October 23, 2026 05:23

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having reviewed a good chunk of the changes this rule would make, I am hitting pause on this review, and want to discuss scaling this rule back quite a bit.

tldr; this change makes many of the steps way more confusing by breaking up the original long sentence into multiple paragraphs. This makes the information much harder to absorb, as the user has to scan through multiple paragraphs to get linked information.

I propose instead that the rule should be altered to make the actual step sentence short, but allow longer explanatory subparagraphs below the step.

Comment thread docs/admin/users/oidc-auth/microsoft.md Resolved
Comment thread docs/admin/users/oidc-auth/microsoft.md Resolved
Comment thread docs/admin/users/oidc-auth/microsoft.md Resolved
Comment thread docs/admin/users/oidc-auth/microsoft.md Resolved
Comment thread docs/admin/users/idp-sync.md Resolved
Comment thread docs/admin/users/idp-sync.md Resolved
Comment thread docs/admin/external-auth.md Resolved
Comment thread docs/admin/external-auth.md Resolved
nickvigilante and others added 3 commits October 26, 2026 17:57
…tyle-guide-make-the-20-word-step-budget-a-limit-and-add

# Conflicts:
#	docs/.style/content-guidelines.md
#	docs/.style/style-guide/README.md
#	docs/admin/networking/stun.md
#	docs/admin/templates/creating-templates.md
#	docs/admin/templates/extending-templates/prebuilt-workspaces.md
#	docs/user-guides/desktop/index.md
#	docs/user-guides/workspace-access/jetbrains/toolbox.md
Narrow the rule to the first paragraph of each ordered-list step, so
explanatory paragraphs below the instruction can run longer. Redo the
cleanup from main: shorten each long instruction or move its explanation
into one paragraph below it, instead of splitting explanations across
several short paragraphs.
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

@ianjevans I narrowed the rule as you proposed. It now counts only the step's instruction (its first paragraph), and explanatory paragraphs below it aren't limited. I reset the content to main and redid the cleanup so explanations stay together in one paragraph (a52c5ab). Each of your threads has a reply.

Generated by Coder Agents on behalf of @nickvigilante.


This will automatically kick off a `Build` that will remain pending until step 3.

> For more information, consult the [OpenShift Documentation](https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/builds_using_buildconfig/understanding-buildconfigs).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [linkspector] reported by reviewdog 🐶
Cannot reach https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/builds_using_buildconfig/understanding-buildconfigs Status: null Navigation timeout of 30000 ms exceeded

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great. This is a much better solution.

@nickvigilante
nickvigilante merged commit 81c4057 into main Oct 27, 2026
31 of 32 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-1272-style-guide-make-the-20-word-step-budget-a-limit-and-add branch October 27, 2026 00:43
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 27, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants