Skip to content

docs: align documentation wording and Vale linting#297

Merged
choufraise merged 20 commits into
mainfrom
docs/alignment
May 12, 2026
Merged

docs: align documentation wording and Vale linting#297
choufraise merged 20 commits into
mainfrom
docs/alignment

Conversation

@choufraise
Copy link
Copy Markdown
Collaborator

Summary

  • Align README, website docs, contributor docs, ADRs, and issue templates with current wording.
  • Add Vale coverage for MDX docs and project-specific vocabulary.
  • Exclude generated references and code fragments where Vale creates stale/noisy findings.
  • Clarify natsClusterRef fallback documentation and sync generated CRD docs.
  • Fix smaller documentation issues, typos, heading style, and public NAuth copy.

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 vale

Commits

  • docs: standardize mise task shorthand
  • docs: fix ServiceMonitor CRD typo
  • docs: clarify natsClusterRef fallback behavior
  • docs: normalize public NAuth copy
  • docs: lint MDX documentation with Vale
  • docs: expand Vale vocabulary for project terms
  • docs: fix remaining Vale spelling errors
  • docs: normalize project terminology casing
  • docs: skip code scopes in Vale
  • docs: exclude generated reference docs from Vale
  • docs: clear remaining Vale prose errors
  • docs: apply Vale preferred wording
  • docs: remove future-tense Vale warnings
  • docs: remove ellipses from issue templates
  • docs: remove first-person example wording
  • docs: resolve Oxford comma warnings
  • docs: resolve Vale colon-style warnings
  • docs: remove collective-pronoun Vale warnings
  • docs: align Markdown headings with Vale style
  • docs: fix bug report template wording

choufraise added 20 commits May 11, 2026 14:55
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>
@choufraise choufraise requested a review from a team as a code owner May 12, 2026 06:03
@choufraise choufraise merged commit 97cdd4f into main May 12, 2026
10 checks passed
@choufraise choufraise deleted the docs/alignment branch May 12, 2026 10:23
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.

2 participants