Documentation is cool again

Table of contents

• Premise
• The documentation renaissance
• Why agents love good docs
  • Context is King
  • Consistency Matters
  • Examples Drive Understanding
• No more an afterthought
• The new documentation paradigm
  • Documentation as Infrastructure
  • Living Documentation
  • Multi-Audience Optimization
• My tips for agent-friendly documentation
  • Structure for Scannability
  • Keep It Concise Yet Meaningful
  • Be Explicit About Context
  • Rich Examples and Use Cases
  • Maintain Accuracy
• Final thoughts

Premise

Unless you've been living in a cave for the last few months, you've probably noticed the explosion of AI-powered development tools. Claude, GitHub Copilot, Cursor, Windsurf, and a dozen other agents have burst onto the scene, promising to revolutionize how we write code. And honestly? They're pretty incredible.

These tools can generate entire functions from a simple comment, refactor legacy code in seconds, and even debug complex issues faster than many seasoned developers. It feels like having a brilliant junior developer sitting right next to you - one who never gets tired, never needs coffee breaks, and can instantly recall patterns from millions of codebases.

But here's the thing: like any promising junior developer, these agents are far from perfect. They can write elegant solutions one moment and produce completely broken code the next. They might confidently suggest an approach that worked well in their training data but completely misses the specific context of your project. They excel at pattern matching but often struggle with the nuanced understanding that comes from knowing your business logic, your team's conventions, or the historical reasons why certain decisions were made.

The difference between getting excellent results and frustrating failures often comes down to one thing: context. Give these agents rich, well-structured information about your codebase, and they'll surprise you with their capabilities. Leave them to guess, and you'll spend more time fixing their mistakes than you would have writing the code yourself.

This is where documentation becomes not just helpful, but absolutely critical.

The documentation renaissance

For years, documentation has been treated as a necessary evil - something developers reluctantly write and rarely maintain. It was often outdated, incomplete, or buried so deep that finding the right information felt like archaeology.

But something fundamental has changed. With the rise of AI agents and coding assistants, documentation has suddenly become cool again. And it's not just cool - it's absolutely critical.

When I talk about documentation here, I mean more than just traditional README files and API docs. I'm referring to the entire ecosystem of knowledge that helps both humans and machines understand your code: clear comments, well-structured code, comprehensive tests, meaningful variable names, and yes, those README files too. It's all the context that makes a codebase approachable and maintainable.

Why agents love good docs

AI agents are voracious consumers of structured information. Unlike humans who can fill in gaps with intuition and experience, agents need clear, comprehensive, and well-organized documentation to function effectively.

Here's why good documentation is an agent's best friend:

Context is King

Agents excel when they have rich context about your codebase, APIs, and business logic. Well-written documentation provides this context in a digestible format that agents can quickly parse and understand.

Consistency Matters

Agents thrive on patterns and consistency. When your documentation follows a predictable structure and style, agents can more easily extract relevant information and apply it correctly.

Examples Drive Understanding

Code examples in documentation aren't just helpful for humans - they're training data for agents. The more comprehensive and accurate your examples, the better agents can understand and replicate patterns in your codebase.

No more an afterthought

Claude reading the CLAUDE.md file to understand that it should use a just recipe for running integration tests.

What's fascinating is that AI agents themselves are now natively accommodating and even requesting better documentation. This isn't just about agents consuming existing docs - they're actively pushing us toward better documentation practices.

Take Claude, for example. When working with code, Claude can automatically look for and utilize CLAUDE.md files in projects. These files serve as specialized documentation that provides context, preferences, and guidelines specifically for AI agents working on the codebase. It's documentation written by humans, for machines, that ultimately benefits everyone.

I recently added a CLAUDE.md file to one of my company's open source projects. This file includes everything from build commands and testing guidelines to pull request conventions and release processes. It's like having a detailed onboarding document that agents can reference to understand not just what the code does, but how the team works with it.

This represents a fundamental shift: we're moving from documentation as an afterthought to documentation as a first-class citizen in our development workflow. Agents aren't just tolerating our poor documentation habits - they're incentivizing us to do better.

Claude's CLAUDE.md approach isn't the only emerging standard in this space. The community is also developing other conventions like llms.txt, which proposes a standardized /llms.txt file that websites can use to provide LLM-friendly content. This file offers curated information specifically formatted for AI consumption, helping agents quickly understand and navigate website content without having to parse complex HTML structures.

These emerging standards signal that we're entering a new era where documentation designed for AI agents is becoming just as important as documentation designed for humans - and often, the same principles that make docs great for agents make them better for humans too.

The new documentation paradigm

The agent revolution is changing how we think about documentation:

Documentation as Infrastructure

Good docs are no longer just nice-to-have - they're infrastructure. They're the foundation that enables agents to understand, navigate, and contribute to your codebase effectively.

Living Documentation

With agents helping to maintain and update documentation, we can finally achieve the dream of living docs that stay current with the code.

Multi-Audience Optimization

Modern documentation needs to serve both human developers and AI agents. This dual audience is actually making docs better for everyone.

My tips for agent-friendly documentation

Through my first experiences working with AI agents and implementing documentation standards like CLAUDE.md files, I've learned a few things about what makes documentation truly effective for both humans and machines. Here are the practices that have worked best for me:

Structure for Scannability

• Use clear headings and subheadings
• Include table of contents for longer documents
• Organize information hierarchically
• Use consistent formatting and conventions

Keep It Concise Yet Meaningful

• Focus on essential information that adds real value
• Avoid verbose explanations when simple ones suffice
• Use lightweight formats like Markdown that minimize structural overhead
• The best documentation often has the least formatting complexity

Be Explicit About Context

• Include purpose statements for modules and functions
• Document assumptions and constraints
• Explain the "why" behind design decisions
• Provide business context when relevant

Rich Examples and Use Cases

• Include comprehensive code examples
• Show common usage patterns
• Document edge cases and error handling
• Provide end-to-end scenarios

Maintain Accuracy

• Keep documentation in sync with code changes
• Use automated tools to validate examples
• Regular audits and updates
• Version documentation alongside code

Final thoughts

The rise of AI agents has fundamentally shifted the value proposition of documentation. What was once a chore has become a competitive advantage. Teams with excellent documentation will find their agents more capable, their onboarding faster, and their development cycles more efficient.

Documentation isn't just cool again - it's becoming the secret weapon of high-performing development teams. The question isn't whether you can afford to invest in better documentation, but whether you can afford not to.

In my opinion, every software engineer should start using these AI development tools today. They're not perfect, but they're already transformative when used correctly. Think of them as multipliers: if you feed them good practices, clear documentation, and well-structured code, they'll amplify these positive inputs and help you achieve better outcomes. But multiply poor practices by AI assistance, and you'll only get worse results faster.

The engineers who learn to work effectively with AI agents - who understand how to provide context, write clear documentation, and structure their projects for both human and machine consumption - will have a significant advantage in the years to come. Don't wait for these tools to get better. Start learning how to work with them now.

In the age of agents, good documentation isn't just helping humans understand your code - it's teaching machines to be better partners in building it.