docs: align documentation wording and Vale linting#297
Merged
Conversation
Mise supports running tasks directly as `mise <task>`, and the shorter form is the preferred project style. Use it consistently across contributor, local, and examples documentation. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
The Helm values comment misspelled "Requires", and the generated chart README repeated the typo. Fix both so chart documentation reads cleanly. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
The API docs still said account cluster references defaulted to legacy behavior. Clarify that the controller uses the operator-level NATS_CLUSTER_REF when configured and otherwise fails if no target NatsCluster can be resolved. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Public-facing docs mixed casing, symbols, and terms that failed Vale or read inconsistently. Normalize the README, Getting Started guide, and homepage tagline so the main project docs match the repo style rules. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale only covered Markdown files, so authored MDX docs could drift from the prose rules. Map MDX to Markdown, ignore MDX import syntax, and add a public docs lint task with Vale pinned in Mise. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale flagged common Kubernetes, NATS, Helm, and generated API terms as spelling errors, which hid the real prose issues. Add accepted project vocabulary so future Vale runs surface actual documentation problems. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale still flagged two real spelling issues after the vocabulary cleanup. Fix the misspelled ADR status text and use the correct JetStream product casing in the issue audit. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Several prose docs still used older Nauth/nauth casing and inconsistent NATS product terms. Normalize reader-facing terminology to NAuth, NATS, and JetStream, and allow both AuthN/AuthZ and authn/authz in Vale so the linter matches the project’s accepted vocabulary. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale was linting Markdown and MDX code fragments as prose, which made API identifiers compete with normal wording rules. Skip code scopes and normalize URL vocabulary so valid prose and generated identifiers can coexist. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale was still linting generated Helm chart tables and CRD reference output as normal prose, producing false positives for API identifiers. Exclude those generated Markdown files so Vale focuses on authored docs. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale still reported hard prose errors for exclamation points and Latin abbreviation style in authored docs. Replace those with plain punctuation and wording so the remaining Vale backlog is warning-only. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale flagged several authored docs for discouraged wording such as e-mail, open-source, in order to, functionality, k8s, and file name. Use the preferred terms so the warning backlog is smaller and more focused on style-only cleanup. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale flagged future-tense wording across contributor docs, ADRs, and reference notes. Rewrite those lines in present tense so the docs read more directly and the warning backlog stays focused on style cleanup. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale flagged placeholder ellipses in the GitHub issue templates. Replace them with explicit placeholder labels so the templates stay clear without triggering prose lint warnings. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale flagged first-person phrasing in the ADR worklog example. Rewrite the example as direct statements so it stays clear without depending on quoted first-person text. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale flagged one authored ADR list and one false positive in the Contributor Covenant text. Clarify the ADR list and locally suppress the standard Code of Conduct phrase so Oxford comma warnings are gone. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale flagged uppercase text after colons in Code of Conduct labels and ADR status/link text. Move label punctuation into the bold labels and simplify ADR references so colon-style warnings are removed. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Vale flagged first-person plural wording in contributor docs, security docs, issue templates, and ADR notes. Rewrite project-authored phrasing and suppress the rule for the standard Code of Conduct text where the collective voice is intentional. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Normalize tracked Markdown headings to sentence-style capitalization and add narrow Vale suppressions for proper names/templates. Why: This clears the remaining Vale heading warnings while preserving standard wording where rewriting would reduce accuracy. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
Correct a typo in the version prompt. Why: The issue template should read cleanly when users report bugs. Signed-off-by: Thobias Karlsson <thobias.karlsson@gmail.com>
eufriction
approved these changes
May 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
natsClusterReffallback documentation and sync generated CRD docs.Why
This keeps GitHub and nauth.io documentation cleaner, more accurate, and easier to maintain while making Vale useful for real documentation problems instead of project terms and code snippets.
Validation
git ls-files -z '*.md' '*.mdx' | xargs -0 valeCommits