March 11, 2026
Docs vs Bots: Choose your fighter
Docs directories are doomed
Dev drama erupts: is your /docs a junk drawer or a bot trap
TLDR: A new post claims the trusty /docs folder is a failing stopgap and can’t keep up with AI-assisted coding. The comments explode: some want AI agents to auto-update docs, others insist docs stay human-first, and many smell a stealth sales pitch—complete with “1985 called” and “junk drawer” jokes.
The blog declares the humble /docs folder—those markdown files that explain your code—on borrowed time. It argues that as teams feed chatbots (LLMs, the AI text tools that write code) more context, these folders rot: hard to find stuff, no clear owner, inconsistent updates, and zero map of how files link. It even insists “LLMs won’t save us,” because context is human intent, not something a model can conjure. It name‑drops that big shops like OpenAI started this way, then asks why we’re still using a “1985” solution today.
Cue the comments, and wow—fireworks. One reader who’s “AI‑positive” says AI‑looking diagrams from “Nano Banana Pro” make them nuke the tab, while another fires back: “If you can’t keep docs in sync, let the agent do it—and keep docs in the repo.” The human‑first camp claps back: “I want my docs for people, not bots.” A cynic goes full office‑politics, claiming this is just to justify machines dumping “1,000’s of lines of debt” while managers dream of cutting pesky engineers. Others say the post reads like an ad for a product that doesn’t exist. Jokes fly—“1985 called, it wants its docs back,” “/docs is my junk drawer,” and “RIP /docs” memes. Verdict? A messy, hilarious split between bot‑butlers and documentation romantics.
Key Points
- •The /docs directory often emerges organically to provide context for LLM-assisted development.
- •As documentation grows, inconsistencies and lack of observability degrade LLM-generated code quality.
- •The article identifies six issues: discoverability, ownership/domain expertise, doc rot, velocity mismatch, lack of hierarchy, and bespoke structures.
- •LLMs are unlikely to solve context production and management because context defines intent and constraints beyond code.
- •The author calls for more robust context management approaches, asserting current meager context is a key blocker.