Should internal docs be written for humans, agents, or both? A two-track documentation workflow
MenuNo294 · reddit · 2026-09-14
A developer who lets AI agents write and maintain most of his engineering docs (runbooks, ADRs, session notes) proposes a two-track approach: human-facing docs get rich context and readable formatting, while agent-facing docs are optimized for token efficiency with linked glossaries and indexes agents can traverse themselves. Since some docs will likely never be read by humans, he argues, writing them for human readability is wasted effort — and asks whether docs should always default to human-first.
More from coding & agent
- Muse Spark 1.3 wins fans: browser agent files insurance claims faster than humans — alexandr_wang · 2026-09-14
- Alexandr Wang touts Muse's onboarding design for non-AI-savvy users — alexandr_wang · 2026-09-14
- Dev hooks Teenage Engineering MicFX mic to voice-control Claude and Codex coding agents — narphorium · 2026-09-14
- Voice-chat with ChatGPT from your phone while walking: a recipe for flow state — daniel_mac8 · 2026-09-14
- User reports Amp Code orb sandbox lost its entire filesystem with no recovery path — carlosdponx · 2026-09-14
- UMass AutoIndex Turns Chunking Into Programs an LLM Writes, Not Configs You Tune — mrdrozdov · 2026-09-14