Docs: edit out the AI-generated voice (the 'no X, no Y' tell) — make the docs read like a human wrote them

[VijitSingh97]

Problem

The docs read as machine-generated. The biggest tell is negative parallelism — the "no X, no Y" / "not X, it's Y" antithesis — but it shows up alongside a cluster of other LLM-prose habits: heavy em-dash dependence, everything-in-bold, triadic list rhythm, and marketing adjectives. For a privacy/security project where the whole pitch is trust me with your wallet and your IP, prose that pattern-matches to "AI slop" actively undermines credibility. The docs should read like a human who runs this stack wrote them.

This is a voice/tone editing pass, not a content rewrite — every technical fact, command, flag, and number must stay correct. We're changing how it reads, not what it says.

The tells (with examples)

1. "no X, no Y" negative parallelism — the headline offender:

• docs/releasing.md:129 — "Images are pulled from GHCR — no local build, no compile wait."
• docs/faq.md:32 — "no wallet address, no pool URL juggling."
• docs/faq.md:28 — "no public port forwarding, and Monero/Tari traffic runs over Tor."
• docs/integration-testing.md:130 — "no config change, no apply, no restore."
• docs/test-server-architecture.md:141 — "no reconfiguration, no re-sync."
• docs/testing-strategy.md:190 — "no leaks, no log/DB growth runaway."

2. Em-dash antithesis & general em-dash overuse — density is very high in places:

• docs/configuration.md (53), docs/test-inventory.md (51), docs/dashboard.md (45), docs/privacy.md (42), docs/releasing.md (40) em-dashes each. Many are the "real point — restated point" rhythm that LLMs lean on. Replace a chunk with periods/commas and vary the cadence.

3. Marketing adjectives / "out of the box" filler:

• README.md:47 — "Hardened out of the box."
• docs/architecture.md:175 — "This happens seamlessly, with no changes on your workers."
• repeated tagline "the whole stack in one command" (README.md:7, docs/faq.md:24, docs/faq.md:135).

4. Over-bolding — most docs bold half the nouns in a sentence, which flattens emphasis. Reserve bold for genuinely load-bearing terms.

Scope

README.md, everything under docs/, and SECURITY.md. (User-facing docs first — getting-started.md, faq.md, architecture.md, privacy.md, configuration.md, workers.md, dashboard.md, hardware.md, operations.md, README.md; the testing/release internal docs are lower priority.)

Approach

• Hunt the patterns, don't blind find/replace — "no X, no Y" is sometimes the clearest phrasing; the goal is to break the monotony, not ban a construction. Rewrite for variety, not by rule.
• Vary sentence length and opening structure; let some sentences just be plain and short.
• Cut em-dash chains; not every clause needs the dramatic pause.
• Demote decorative bold; keep it on terms that carry real weight.
• Drop marketing adjectives ("seamlessly", "out of the box", "hardened by default" as a slogan) in favor of saying the concrete thing.
• Read passages aloud — if it sounds like a launch blog post, redraft it.

Acceptance

• User-facing docs no longer lean on the "no X, no Y" / antithesis rhythm; remaining uses are deliberate, not reflexive.
• Em-dash density meaningfully down in the top offenders; cadence varies.
• No technical regressions — commands, flags, paths, and numbers unchanged (diff-review the facts, not just the prose).
• A maintainer reads a fresh pass and it sounds like a person, not a model.

Related

• Launch assets: refreshed hero screenshot + demo GIF + GitHub social preview #80 — Launch assets (hero/GIF/social) — same "make the project read as credible at launch" goal; worth doing in the same pass.