chore: enforce docs voice + testing guidelines as guardrails#335
Merged
Conversation
Keep the documentation and testing standards front of mind by making them discoverable and, where possible, CI-enforced instead of relying on reviewer memory. - docs/STYLE.md: the house documentation voice (opening line, imperative mood, NOTE warnings, concrete numbers, link-out) + the banned-word list + the code-is-source-of-truth accuracy rule. Points at testing-strategy.md. - scripts/lint-docs-voice.sh + make lint-docs-voice: fail CI if a banned marketing word appears in a prose doc (the one mechanizable slice of the voice guide). Wired into the per-surface lint job. Excludes STYLE.md itself, CHANGELOG, generated, and vendored markdown. Portable (no bash 4 mapfile). - .github/PULL_REQUEST_TEMPLATE.md: two checklist lines — docs in house voice, behaviour tested at the right tier with patch coverage clearing the gate. - CLAUDE.md: repo-root pointer so any Claude session loads CONTRIBUTING + docs/STYLE.md + docs/testing-strategy.md. Passes on develop (29 prose docs, no banned words); shellcheck + shfmt + yamllint + markdownlint clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
VijitSingh97
added a commit
that referenced
this pull request
Jul 2, 2026
* docs: rewrite CONTRIBUTING.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite README.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite SECURITY.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite build/dashboard/README.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/README.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/architecture.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/configuration.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/dashboard.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/faq.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/getting-started.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/hardware.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/integration-testing.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/operations.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/privacy.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/release-server.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/releasing.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/test-server-architecture.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/testing-guide.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/testing-strategy.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite docs/workers.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rewrite images/launch/README.md for voice and accuracy Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: verify hardware.md sizing against live deployments; fix Tari overstatement Checked the [TODO] figures against two live 31 GB-RAM boxes (pithead-prod pruned, gouda full): - Disk confirmed: Monero ~102 GB pruned / ~266 GB full, Tari ~139 GB. Bumped the Tari figure 135 -> 140 GB (measured 138-139, growing) and resolved the TODO. - Fixed an overstatement: Tari (~140 GB) does NOT rival a *full* Monero node (~265 GB) — it's the largest consumer only once Monero is pruned (vs ~100 GB). - Fixed the same mdb_copy error corrected in test-server-architecture.md: reclaim space on an existing full chain with monero-blockchain-prune, not mdb_copy -c. - Clarified the per-service RAM figures are provisioning minimums; steady-state RSS is far lower (monerod/p2pool a few hundred MB; Tari 2-4 GB and climbing). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: fix banned word in monitoring.md (powerful -> high-privilege) monitoring.md landed via #133 before the #335 banned-word gate existed, so it slipped 'powerful' past. Fix it here so develop is green under the new check. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
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
1 participant
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.
Make the documentation and testing standards discoverable and CI-enforced, so they stay front of mind instead of depending on reviewer memory.
What & why
docs/STYLE.md— the house documentation voice (one factual opening line, imperative mood,NOTE:warnings, concrete numbers, link-out) plus the banned-word list and the code-is-source-of-truth accuracy rule. Links todocs/testing-strategy.md.scripts/lint-docs-voice.sh+make lint-docs-voice— CI fails if a banned marketing word appears in a prose doc. This is the one part of the voice guide that can be mechanized; the rest (imperative mood, factual opening) stays a human review. Wired into the per-surface lint job. ExcludesSTYLE.mditself (it lists the words),CHANGELOG.md, generated files, and vendored markdown. Portable — no bash-4mapfile..github/PULL_REQUEST_TEMPLATE.md— two checklist lines: docs updated in the house voice, and behaviour tested at the right tier with patch coverage clearing the gate.CLAUDE.md— repo-root pointer so any Claude session loadsCONTRIBUTING.md+docs/STYLE.md+docs/testing-strategy.md.Verification
make lint-docs-voicepasses on develop (29 prose docs, no banned words).shellcheck+shfmtclean on the new script;markdownlintclean onSTYLE.md/CLAUDE.md;yamllintclean on theci.ymledit.Pairs with #334 (the voice + accuracy rewrite). Do not merge — for review.