It’s one of the four values in the Manifesto for Agile Software Development: “[We value] working software over comprehensive documentation.”
So, can Agile teams skip documentation? What if you’re in a context that values documentation? How should we even think about documentation in Agile?
The original Agile value expressed a tradeoff. The Manifesto authors were saying, “Based on our experience, when have to choose between working software and comprehensive documentation, we’re going to choose the software.” In other words, “We’re willing to get worse at comprehensive documentation in order to get more working software.”
But if you’re doing software development in a big company, “working software over comprehensive documentation” probably feels more like a wish than like practical advice.
So, here’s some practical advice for navigating documentation on an Agile team (including how AI can and can’t help)…
Start with the “why” of your product
In order to evaluate whether a particular activity or artifact is adding value, you need a clear understanding of the value your product delivers. What outcomes are you trying to create? What problems are you trying to solve? For whom? Over what timeframe (i.e., is this a short-term fix or a long-term solution)?
This isn’t the “why” of your documents. We’ll get to that. This is about the “why” of the *product* that the documents support. Starting here ensures that any documentation is in service of the larger goal of the product.
Who else is involved in your product’s “why”?
For all but the simplest products in the simplest contexts, there’s a constellation of stakeholders who affect and are affected by your product. Buyers and users, certainly. But also business leaders, finance, compliance, other product teams, support and operations people, future developers who will have to maintain and extend the product, etc.
List out all those stakeholders. At this point, go broad. If you think someone might have a stake in your product’s outcome, include them on the list.
Documentation is part of the product
Now that you’ve laid out what value you’re trying to create and who’s involved, ask, “What needs do people have around this product that the product itself won’t be able to meet?”
Maybe it’s not obvious how users can get started with the product. Perhaps support people need to understand how to access monitoring data for troubleshooting. Compliance people may need to communicate with auditors about how the product follows the rules. Future developers will want to make sense of the code so they can maintain and extend it.
Documents, like features, do jobs for people. Understanding those things your stakeholders need to accomplish or make progress on and how your documents can help is key.
Many of the usual customer research techniques work for understanding these stakeholders. Do interviews. Do observation. Make paper prototypes. Run A-B tests.
Once you understand the needs that documentation should address, you can figure out the best way to meet those needs. You’re no longer creating documents simply because a process demands it.
Grow documentation incrementally
So, you’ve identified what documentation needs to be part of your product, but when do you create those docs?
We recommend not saving documentation for the end of a release. Instead, grow your documents incrementally as you grow your software. At any point, the documentation should tell the truth about the current state of the system.
Make documentation part of your definition of done. Don’t call a user story done until the docs are done, too. Make appropriate commitments so you have capacity for this extra work—it needs to be done sometime.
But what if documentation is done by a group outside your team? In that case, create the documents that could serve as a first draft for them to iterate on once they start working on your project, and build those ‘draft one’ docs incrementally.
Consider a document inventory
You’re probably not creating a process from scratch. So, it can be useful to do a document inventory.
On a whiteboard or in a virtual collaboration tool like Miro, make a list of all the documents you create today. Note who uses each one and what they use them for.
Then, go through each one and ask, “Are the current documents succeeding at the jobs they’re intended to do for these people?” If the answer is, “no,” brainstorm ways to improve (or replace) that document with something better.
What About AI?
A few people love writing docs, but most software teams would rather spend their time on design and code, so people are reaching for AI tools as a way to make documentation work go away. But if you want to create useful docs, AI tools don’t eliminate documentation work, they just change the work.
There’s something seductive about the promise of AI-generated documentation—no more blank pages, no more struggling to explain complex systems, no more hours spent writing docs when you could be coding. But documentation isn’t just about having words on a page. It’s about having the right words that solve real problems for your stakeholders.
While AI can generate plausible-sounding technical content, it can’t determine which parts of your system actually need documenting. It can’t observe users struggling with unclear interfaces or anticipate questions based on your organization’s history. And it certainly can’t validate that what’s documented matches what’s actually implemented.
The writing process itself often clarifies thinking—when we shortcut that process, we risk missing the deeper understanding that comes from figuring out how to explain something to someone else. And let’s be honest about our human tendencies: how thoroughly do we actually review generated content? Reviewing can be even more tedious than writing from scratch.
If you’re looking to integrate AI into your documentation workflow, think beyond just generating drafts. Consider where your current documentation process actually breaks down. Is it consistency across a large system? Translating technical concepts for different audiences? Maintaining docs as your system evolves? Those might be places where AI tools can genuinely enhance your process rather than just changing where the work happens.
We recommend taking a Theory of Constraints approach. Start by figuring out what docs you need to create and for whom. Identify the constraint in that process. Only then, evaluate which tools (AI or otherwise) might help you address that constraint.
We’d love to hear from you… What’s one thing from this article that you’re going to use to improve your documentation approach? Email us at mailbag@humanizingwork.com.
Last updated