Skip to content

docs: rewrite for voice consistency and factual accuracy#334

Merged
VijitSingh97 merged 24 commits into
developfrom
docs/voice-and-accuracy
Jul 2, 2026
Merged

docs: rewrite for voice consistency and factual accuracy#334
VijitSingh97 merged 24 commits into
developfrom
docs/voice-and-accuracy

Conversation

@VijitSingh97

@VijitSingh97 VijitSingh97 commented Jul 2, 2026

Copy link
Copy Markdown
Collaborator

A voice + accuracy pass over every prose doc, matching the cadence of the p2pool / xmrig / monero READMEs: one factual opening line, imperative procedures, plain NOTE: warnings, concrete numbers/ports/flags, link out instead of inlining, zero marketing.

Primarily voice. Technical facts, commands, flags, addresses, and ports are unchanged except where a doc was factually wrong versus the code — those are corrected and listed below. Every command, flag, default, and port was verified against the actual source (pithead, docker-compose.yml, config.reference.json, config.py, Dockerfiles, Makefile, test scripts). One commit per file for independent review.

Not touched (already in voice, or out of scope): docs/benchmarks/tor-vs-clearnet.md, tests/integration/README.md, tests/integration/testbench-README.md (no changes needed); CHANGELOG.md + docs/test-inventory.md + generated/vendor/template files (excluded by design).

1. Files changed (21)

File What shifted
README.md Flat spec-driven intro; tightened quickstart. No commands/facts changed.
docs/README.md One-line factual pointer opening; cut the "new here?" softener.
docs/getting-started.md Factual opening line; body already imperative.
docs/configuration.md Tightened intro/prose; the config-key reference table left as-is (already code-accurate).
docs/workers.md Dropped marketing cadence; tables/commands untouched.
docs/architecture.md Flat opening; removed pitch framing; mermaid diagram + facts intact.
docs/privacy.md Tightened narrative; fixed one stale checklist item (below).
docs/operations.md Factual lead; every pithead subcommand re-verified against the script.
docs/dashboard.md Factual voice; fixed the Syncing... badge text (below).
docs/hardware.md Spec-driven prose; sizing verified against two live boxes; fixed the Tari overstatement + an mdb_copy error.
docs/testing-strategy.md Factual cadence; removed a stale hard test-count.
docs/testing-guide.md Fixed a wrong test path; retitled "Philosophy" → "Principles".
docs/integration-testing.md Light tightening; all run.sh flags verified.
docs/releasing.md Spec prose; corrected VERSION, image names, Tari pin, stale claim (below).
docs/release-server.md Tightened opener; commands/paths verified.
docs/test-server-architecture.md Voice; corrected the LMDB compaction command (below).
docs/faq.md Removed "vs. doing it yourself / vs. Gupax" pitch framing; facts verified.
CONTRIBUTING.md Imperative voice; corrected the branch model maindevelop (below).
SECURITY.md Removed pitch framing; reporting process kept verbatim.
build/dashboard/README.md Corrected frontend-test claims; added sim/; fixed the node --test invocation (below).
images/launch/README.md Light touch; dropped the "Marketing/" label.

2. Accuracy corrections

File:line Claim as written What the code says Source
docs/privacy.md "Route P2Pool outbound through Tor by editing its compose command:" P2Pool is Tor-by-default in v1.1; pithead injects --socks5 <prefix>.25:9050 --socks5-proxy-type tor. Knob is p2pool.clearnet (default false). No compose editing. pithead:1149, config.py:132
docs/dashboard.md:15 Syncing… (Unicode ellipsis) Code emits Syncing... (three ASCII dots) web/views.py:682
docs/testing-strategy.md:22 "The dashboard has ~140 unit tests" ~600 dashboard test functions today; stale figure removed (no hard count to rot) grep 'def test_'
docs/testing-guide.md:38 tests/service/test_data_service.py Actual path build/dashboard/tests/service/test_data_service.py repo layout
docs/releasing.md "VERSION is 0.1.0" VERSION is 1.0.3 VERSION:1
docs/releasing.md "one remaining piece is wiring ${STACK_VERSION} into compose" Already wired docker-compose.yml:20,51,…
docs/releasing.md Image names dashboard, p2pool, … Published as pithead-* docker-compose.yml:20,51,…
docs/releasing.md Tari minotari_node:vX-mainnet Pinned v5.3.1-mainnet by digest docker-compose.yml:107
docs/test-server-architecture.md Compaction via mdb_copy -c monero-blockchain-prune --copy-pruned-database (mdb_copy fails MDB_VERSION_MISMATCH on Monero's patched LMDB) tests/integration/compact-chain.sh:15-16,49
CONTRIBUTING.md:32,69 Branch off / target main Integration branch is develop (main is released-only) .github/workflows/ci.yml:5, Makefile:12
build/dashboard/README.md:30-33 "Component rendering has no unit tests; manual browser smoke test" tests/frontend/components.test.mjs renders every card through App against a real build_state() fixture build/dashboard/tests/frontend/
build/dashboard/README.md:48 Layout tree omits sim/ mining_dashboard/sim/donation_model.py exists dir listing
build/dashboard/README.md:68 node --test tests/frontend/*.test.mjs CI uses node --test tests/frontend/ test headers
docs/hardware.md "Tari's chain rivals a full Monero node" Tari ~140 GB vs a full Monero node ~265 GB — it only rivals/exceeds a pruned node (~100 GB) live: pithead-prod 139 GB, gouda 138 GB / 266 GB
docs/hardware.md Reclaim space on a full chain by compacting with mdb_copy -c Monero's patched LMDB rejects mdb_copy; use monero-blockchain-prune tests/integration/compact-chain.sh:15-16
docs/hardware.md Tari disk ~135 GB measured ~138–139 GB and growing → ~140 GB live: pithead-prod/gouda

3. Open items

  • docs/hardware.md — the sizing figures were verified against two live 31 GB-RAM deployments (pithead-prod pruned, gouda full): Monero ~102 GB pruned / ~266 GB full and Tari ~139 GB confirm the documented disk sizes; the per-service RAM figures are provisioning minimums (real RSS is far lower). The [TODO] is resolved and removed.

Do not merge — for review.

VijitSingh97 and others added 21 commits July 2, 2026 14:58
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
VijitSingh97 and others added 3 commits July 2, 2026 15:14
…erstatement

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>
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>
@VijitSingh97 VijitSingh97 merged commit ef6449f into develop Jul 2, 2026
16 checks passed
@VijitSingh97 VijitSingh97 deleted the docs/voice-and-accuracy branch July 2, 2026 20:33
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.

1 participant