docs: rewrite user-facing docs in a plainer voice - #31
Merged
Conversation
Strip the AI tells from README, docs/, CONTRIBUTING and recording/README:
remove all 111 em dashes, break up the bolded-lead-in walls, cut inflated
phrasing ("wishful thinking", "degrades honestly", "Reproducible pipeline")
and rule-of-three padding.
Also:
- drop the "Imagine this" hypothetical from the README
- link docs/safety.md from the README, which nothing pointed at before
- fix "init detects candidates from, grouped as..." in setup-delegation.md
No technical claims, numbers, tables or code samples changed.
- max_output_bytes is a base cap, not a hard cap: a single read may return up to 8x it (service.ts clamps to min(max_bytes, maxOutputBytes * 8)). Fixed in docs/configuration.md and in the config template that `sidemux init` scaffolds into ~/.config/sidemux/config.toml. - README quoted a truncated form of the missing-tmux error; now describes it as a prefix rather than misquoting the full string. - safety.md classified only 7 of the 8 tools, omitting `status`. Now accounts for all eight, four writing and four observing.
tomfordweb
force-pushed
the
docs/voice-rewrite
branch
from
July 25, 2026 12:36
1a190f0 to
256e9b9
Compare
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.
Passes the docs through the humanizer rules and the personal writing-voice guide. Register stays third person and technical; this is a voice pass, not a content edit.
What changed
docs/*.md, CONTRIBUTING andrecording/README.md. Each one became a sentence break, colon, comma or paren. The only—left are the three "no reduction" cells in the benchmark tables, which are data.Two real fixes that came out of it
docs/safety.mdwas not linked from anywhere. The README Tools section now points at it.setup-delegation.mdhad "initdetects candidates from, grouped as test / lint / build / dev:", which is missing a word.Not touched
Agent-facing files (
skills/tmux-delegate/SKILL.md,AGENTS.md,CLAUDE.md,commands/) keep their terse imperative register, which is correct for models.CODE_OF_CONDUCT.mdis verbatim Contributor Covenant.The README env var table still duplicates
docs/configuration.mdin full. Left alone deliberately; worth a separate call on whether to trim it.Verification
Full local gate (build, typecheck, lint, test) green.
git diff --stattouches 9 markdown files and no source. No technical claim, number, table or code sample changed.The first gate run hit a flaky
job-log.test.tsscrollback-overflow assertion, which passed on rerun and on a full re-run of the suite. Filed assidemux-pbg.