Programmers will document for Claude, but not for each other
Programmers are increasingly willing to document their work for AI, but not for human colleagues, a trend that's sparking a lively debate on Hacker News. This shift highlights a fundamental difference in incentives: AI models consistently 'read' and leverage documentation for immediate benefit, making the effort feel worthwhile. The discussion dives deep into the changing nature of documentation, developer workflows, and the evolving role of AI in coding.
The Lowdown
The author, Mark Dominus, recounts a common complaint: programmers are eager to write detailed documentation (like CLAUDE.md) for AI models but less so for human co-workers. He then shares his own evolving experience with using AI, specifically Claude, to generate and maintain project documentation, ultimately finding significant value in the process.
- The Initial Complaint: Programmers express frustration that colleagues dedicate time to documenting for AI, despite historically being reluctant to document for each other.
- Author's Breakthrough: Dominus initially used Claude for temporary handoff documents but realized their long-term value. He began committing these notes to the repository.
- Refined Process: He evolved his method to have Claude write a structured, high-level project summary from scratch at the end of each project.
- Review and Oversight: He carefully reviews and edits Claude's output, ensuring accuracy and taking full responsibility for the committed documentation.
- Efficiency Gains: Claude's summaries are often as good as human-written ones, but take seconds to generate and significantly less time to review compared to writing them manually.
- AI Quirks: He notes an instance where Claude copied a meta-comment from a previous report, highlighting the need for careful oversight and clear instructions.
Dominus concludes with advice to check AI-generated notes and project summaries into repositories, acknowledging that while it seems obvious in hindsight, it represents a new paradigm in developer practices.
The Gossip
AI's Avidity, Human Apathy
The most prevalent theme revolves around the observation that AI, unlike human colleagues, consistently reads and utilizes documentation. Commenters express frustration with humans who bypass existing docs to ask questions, making documentation efforts feel thankless. The immediate, tangible benefit of AI's 'reading' capacity, contrasted with perceived human apathy, creates a strong incentive for developers to document meticulously for AI agents.
The Calculus of Contribution
This theme explores the shifting incentives behind documentation. Many argue that writing for AI provides a direct, measurable return on investment: improved AI performance, greater personal productivity, and saved tokens. In contrast, documenting for human peers often lacks clear incentives, doesn't directly contribute to individual performance metrics, and can feel like thankless work. The cost-benefit analysis drastically favors documentation when an AI is the 'reader.'
Documenting for the Digital Dawn
Commenters delve into how AI is fundamentally reshaping the nature of documentation and the developer's role. Some envision a future where docs are primarily prompts for AI, leading to 'agentic coding' and potentially a 'massive wave of depression' as human tasks become AI-centric. Others see increased utility for architecture and design documents, as AI can now effectively translate them into code. There's also debate on the quality of AI-generated documentation, with concerns about verbosity, staleness, and accuracy, but also appreciation for its ability to provide a starting point or streamline complex tasks.