The wiki is an anti-pattern: docs must live in the repo for coding agents to maintain
TechPreacher · x · 2026-09-25
Microsoft FDE Sascha Corti backs Michael Heap's take that GitHub wikis are an anti-pattern: documentation describes a specific version of your code, so it must be versioned, reviewed and shipped with it.
Why wikis fail:
- GitHub wikis (REPO.wiki.git) and Azure DevOps provisioned wikis are separate repos that never branch or tag with your code
- Wiki edits skip PRs, so required reviews, CODEOWNERS and status checks never run
- CI can't lint, link-check or gate docs it never sees
- git clone excludes the wiki, so IDEs, grep and coding agents can't see or update it
- Most GitHub wikis aren't indexed by search engines; Azure DevOps wikis use proprietary syntax
The fix: keep docs in a docs/ folder, review via PR, gate in CI, and publish with GitHub Pages or Azure DevOps "Publish code as wiki". With coding agents writing much of the code, only in-repo docs can stay current.
More from coding & agent
- Practical guide to shipping MCPs users want: match your dashboard, skip CodeMode, add docs search — teropa · 2026-09-25
- SkillsBench accepted at NeurIPS 2026: 87-task benchmark tests whether agent skills actually help — HanchungLee · 2026-09-25
- Neo Roundtable: a tiny shared conversation layer so ChatGPT, Claude and coding agents stop re-explaining your project — gambit2054 · 2026-09-25
- Dev builds local AI GTM workflow, argues the next platform entry point is hardware-bound — dotey · 2026-09-25
- TypeSafe AI launches Jev, a 'System One' model for bounded decisions in agent runs — hardimanjames · 2026-09-25
- "Astra, get me 99 fishing": one-line prompt sends an AI agent grinding RuneScape — justalexoki · 2026-09-25