Repository navigation
feat: enable Coder.StepLength Vale rule - #30791
nickvigilante merged 10 commits into
Conversation
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
0f650a2 to
e566290
Compare
e566290 to
987e4af
Compare
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
ianjevans
left a comment
There was a problem hiding this comment.
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.
…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.
|
@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 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). |
There was a problem hiding this comment.
🚫 [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
left a comment
There was a problem hiding this comment.
Great. This is a much better solution.
Adds
Coder.StepLength, a Valescriptrule 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.
warning.docs/**exceptdocs/.style/style-guide/**.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 0Coder.StepLengthfindings, and the other rules report no new findings on the changed files.docs/reference/{api,cli,agent-api},configuration-reference.md,prometheus.md): no findings, so no.vale.iniexclusion is needed.Linear: DOCS-1272
Decision log
Review change (Ian's review)
The cleanup for it chopped explanations into several short paragraphs, which made steps harder to read and sometimes changed their meaning.
The content files were reset to
mainand the cleanup was redone against the narrower rule.docs/admin/users/oidc-auth/microsoft.mdkeeps the split into separate steps, with Ian's wording suggestions applied."click" became "select" in step 16 because
Coder.SelectClickflags it.Rule shape
scriptrule (Tengo) withscope: raw, because the count depends on Markdown structure that per-paragraph scopes hide.1.or1)marker.A nested ordered item is its own step.
Bullets, even under a step, are not steps.
<br>, a trailing backslash, or two trailing spaces).\rcounts as whitespace, and offsets come from the raw text.Counting approximations (also in the rule header)
**bold**or__bold__span are one word each.30 secondsare one word.<https://...>autolinks are one word.>in**A** > **B**, is not a word.Tests (fixtures under
/tmp/sltest/, not committed; run with the repo.vale.ini, LF and CRLF)<br>hard break, a long paragraph after a code block, a long nested bullet.fmt/markdown,lint/markdown,lint/emdash,lint/style-claims,lint/typos) pass.The rule is plain text processing, and the CRLF cases simulate Windows line endings on Linux.
Generated by Coder Agents on behalf of @nickvigilante.