Skip to content

docs: split repo docs and wiki on a stated rule; move host runbooks to the wiki - #133

Merged
gatezh merged 1 commit into
masterfrom
docs/wiki-split
Sep 9, 2026
Merged

gatezh merged 1 commit into
masterfrom
docs/wiki-split

Conversation

@gatezh

@gatezh gatezh commented Sep 9, 2026

Copy link
Copy Markdown
Owner

Follow-up to #123. Establishes the boundary between this repo's docs and its wiki, and moves the two documents that were on the wrong side of it.

The rule

If a document goes stale when this repo's code changes, it belongs in the repo. If it goes stale when an external system changes — Docker Desktop, GitHub settings, an upstream tool — or it spans several images, it belongs in the wiki.

Now recorded in .claude/CLAUDE.md, so it doesn't get re-litigated every time a doc is added.

The test does real work. It says per-image READMEs must not move: a tag list or tool table has to change in the same commit as the Dockerfile it describes, and splitting them guarantees drift. It says docs/disk-usage.md and docs/docker-maintenance-cheatsheet.md should move: they describe Docker Desktop's settings-store.json, the vscode volume and a Mac's free space, and nothing in this repo can invalidate them.

What moved

From To
docs/docker-maintenance-cheatsheet.md Docker Disk Maintenance
docs/disk-usage.md Incident: Docker Disk Exhaustion (2026-09-07)

Kept as two pages rather than merged — the cheatsheet is action-first, the incident writeup is the why, and collapsing them buries the commands you need at 2am. Their relative cross-links (./disk-usage.md) were rewritten to wiki links, which would otherwise have 404'd.

The README's two entries are kept and repointed, so the discovery path is unchanged.

What the wiki gained in the same pass

Three consumer-facing pages, because a public repo's wiki should be useful to people using the images, not just to me:

  • Choosing an Image — decision table across the six images, plus the distinction that actually matters: fixed-toolchain images (bun, hugo-bun, …, where the image is the toolchain and the tag says so) versus bring-your-own-toolchain (claude-code, which ships mise but not the tools).
  • Image Tags and Rebuild Policy — the page I think matters most. Nothing previously told a consumer that :latest moves when Renovate bumps a tool, that claude-code:<git-sha> is the only immutable tag published here, or that three of the four tracked tools soak for three days while claude-code does not.
  • Troubleshooting — cross-image symptoms only (Playwright/Chromium, rtk hook inert, container-creation hangs, the rtk name collision, auth, disk), each citing its issue. Anything image-specific stays in that image's README.

Plus _Sidebar.md for navigation, and a rewritten Home carrying the rule and a no-duplication policy: wiki links to READMEs, READMEs link back, and if the same fact appears in both then one is wrong.

Sources on every page

Each wiki page now ends with a ## Sources section citing the PRs and issues its knowledge came from, and a *Last verified:* date. Wiki pages rot silently and have no CI; the date is the cheapest available signal.

Tradeoff being accepted

The moved content is no longer reviewed through a PR, no longer in this repo's git log, and a future change can't update code and that doc in one commit. It has its own history in the wiki's git repo, and it has zero coupling to code here — so nothing that could drift does. That would not be free for anything describing an image, which is exactly why nothing else moved.

Verification

  • All seven wiki URLs return 200 (Home 301s to the wiki root, as it should).
  • grep for disk-usage / docker-maintenance-cheatsheet across the tree: only the two files' own cross-references, both removed with them.
  • No remaining links to docs/*.md from README.md.

Follow-up

The two Docker disk documents added in #123 describe Docker Desktop's
settings-store.json, the vscode volume and a Mac's free space. Nothing in this
repo can invalidate them; they go stale when Docker Desktop changes. Keeping
them in-tree meant they were reviewed on this repo's cadence for no benefit,
and edited through branch -> PR -> CI at exactly the moment you least want that:
during an incident, with a full disk.

Moved to the wiki as "Docker Disk Maintenance" and "Incident: Docker Disk
Exhaustion (2026-09-07)", with their relative cross-links rewritten and Sources
footers citing #123. README keeps its entries, repointed.

The rule that decided it is now in .claude/CLAUDE.md rather than left implicit:
a document that goes stale when this repo's code changes belongs in the repo;
one that goes stale when an external system changes, or that spans several
images, belongs in the wiki. That is why per-image READMEs do not move -- a tag
list has to change in the same commit as its Dockerfile, and splitting them
guarantees drift.

The wiki gains three consumer-facing pages in the same pass (Choosing an Image,
Image Tags and Rebuild Policy, Troubleshooting), so README now points there for
cross-image questions no single README owns.

Tradeoff accepted: the moved content is no longer reviewed in a PR and no longer
in this repo's git log. It has its own history in the wiki repo, and it has zero
coupling to code here, so nothing that could drift does.
@gatezh
gatezh merged commit 2e1a3e7 into master Sep 9, 2026
10 checks passed
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