Shorten and reorganize the docs; facts live in decisions #151

Merged
ethan-hann merged 2 commits from docs-readability into main 2026-10-25 21:04:20 -05:00
Owner

The guides were wordy, repeated ideas and explained the obvious. Each guide now says what its reader needs to act, once; rationale, history and measurements live in docs/decisions.md and the guides cite them (Dn).

User guide: reorganized around the player's path (set up a game, first snapshot, play, go back, profiles, Activity, Free up space, Settings, when something goes wrong); prose about 18% shorter. README: orients without repeating the user guide, about 18% shorter. Developer guide: tests, gates, rules and languages before packaging; about 24% shorter. Architecture: contracts and where code lives, with decision references; 28% shorter. UI guide, testing guide, dogfood checklist and AGENTS.md: tightened, every rule and checklist item kept.

decisions.md: every fact the guides gave up was folded into the decision it belongs to (the docs server setup is now D55's record), and the log was tightened; every Dn heading and item number is unchanged. The docs site builds with warnings as errors and the screenshot coverage tests pass.

The guides were wordy, repeated ideas and explained the obvious. Each guide now says what its reader needs to act, once; rationale, history and measurements live in docs/decisions.md and the guides cite them (Dn). User guide: reorganized around the player's path (set up a game, first snapshot, play, go back, profiles, Activity, Free up space, Settings, when something goes wrong); prose about 18% shorter. README: orients without repeating the user guide, about 18% shorter. Developer guide: tests, gates, rules and languages before packaging; about 24% shorter. Architecture: contracts and where code lives, with decision references; 28% shorter. UI guide, testing guide, dogfood checklist and AGENTS.md: tightened, every rule and checklist item kept. decisions.md: every fact the guides gave up was folded into the decision it belongs to (the docs server setup is now D55's record), and the log was tightened; every Dn heading and item number is unchanged. The docs site builds with warnings as errors and the screenshot coverage tests pass.
Rewritten against the maintainer's brief (too wordy, repeated ideas, over-explained; facts belong in decisions). The user guide follows the player's path, the README orients without repeating it, the developer guide puts tests and gates before packaging, and architecture keeps contracts with decision references. Facts the guides no longer carry are being folded into docs/decisions.md in the next commit.
Merge branch 'integration-0913' into docs-readability
All checks were successful
Gate / linux (pull_request) Successful in 23s
Gate / linux (push) Successful in 12s
Docs / site (pull_request) Successful in 1m38s
Gate / windows (push) Successful in 27s
Docs / site (push) Successful in 1m8s
Gate / windows (pull_request) Successful in 30s
6be916745e
# Conflicts:
#	docs/decisions.md
Sign in to join this conversation.
No reviewers
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
ethan-hann/SavePoint!151
No description provided.