When the Agile Manifesto declared the principle of “working software over comprehensive documentation” in 2001, development teams relished the idea of a new way of working.

Heavy documentation was the status quo but also a barrier to efficiency. It was time-consuming to create, left little room for adaptations, and required ongoing maintenance. This simple line in the Agile Manifesto acknowledged these challenges, and many teams took this as their sign to say goodbye to documentation once and for all.

But teams that stopped creating documentation altogether faced a new set of challenges: They struggled to share knowledge, align on decisions and progress, onboard new team members, or troubleshoot problems. These challenges have intensified over the past few years with the rise of remote work.

It’s clear that heavy, document-driven development isn’t efficient or effective—but neither is eliminating documentation altogether. This begs the question: What is the role of documentation in Agile?

To find out, we talked to James Grenning, one of the original authors of the Agile Manifesto and the founder of Wingman Software. In this interview, Grenning shares the intention behind this commonly misinterpreted line in the Agile Manifesto and discusses how modern-day Agile teams can strike the right balance on documentation to work efficiently.

Take us back in time to the creation of the Agile Manifesto—what prompted this meeting? 

James Grenning: At the time, I was working with Bob Martin, and he asked me if I wanted to participate in the Lightweight Methods Summit at Snowbird Ski Resort in Utah. Lightweight methods referred to approaches like Extreme Programming, Feature-Driven Development, and Scrum—all of which had minimal ceremonies and artifacts compared to the more process-heavy approaches that the ‘80s and ‘90s had been pushing. 

I was a proponent of the Extreme Programming (XP) approach, but there were experts from each of the lightweight software disciplines present at the summit. Although we came from different backgrounds, we shared the desire to improve software development methodologies. Jokingly, we didn’t want to be known as the “lightweights,” so another goal was to determine a new name, which is what we call Agile today.

There was a lot of discussion and differing opinions, with a focus on finding the things we could agree upon. I’m an engineer and was expecting to talk a lot about technical processes, but people and teamwork emerged as major themes. We formed those themes into statements of value, favoring one over another—although we made a point to state that the less favorable are still valuable. This is how we ended up with the four principles you know today.

I didn’t really expect people to care about the Agile Manifesto when Ward Cunningham initially put it up on a website, but a lot of people cared. Although I was surprised, I think it showed just how many people resonated with the challenges in software development and were eager for a better way to work. 

Let’s dive deeper into one of the lines in the Agile Manifesto. What was the original intention behind “working software over comprehensive documentation”? 

JG: The mindset at the time was, “Document it first, then build it.” But documentation is expensive. It’s not just a benefit, it’s a cost.

One goal of traditional documentation was to get the customer’s requests in writing and agreed upon with development upfront so that development could be left alone to build. The problem is that when customers make product requests only once a year, they’re going to ask for everything they can think of—but they’re going to change their minds by the time the software is delivered.

Kent Beck, Ward Cummingham, Ron Jefferies, and other XP enthusiasts knew that creating documentation in this way was not only time-consuming, but it didn’t allow for the team to incorporate learnings or respond to changes. 

The line “working software over comprehensive documentation” represented a fundamental shift in mindset around documentation. It suggested that instead of prioritizing comprehensive documentation upfront, we could incrementally create valuable documentation as we build the software. 

It seems that today, there is a stigma around documentation in Agile. Can you speak to your views on the role of documentation in Agile? 

JG: The form of the statements in the Agile Manifesto took the shape of “one thing over another.” But unfortunately, they’re often misinterpreted as “one thing and not the other.” We see this frequently with documentation. 

Our intention was not to imply that teams shouldn’t produce any documentation. There simply is no single prescription for documentation. The Agile Manifesto is silent about how to approach documentation because we wouldn’t know what to say. Each team’s needs are different. But not giving specific guidance on how to create documentation doesn’t mean you don’t need any. 

Documentation can be incredibly useful for creating a shared understanding across teams and stakeholders. For example, design documentation is necessary for system maintenance, outside reviewers, and remote developers. The key is recognizing that documentation needs vary based on factors like team size, distribution, regulation, or industry.

I’d recommend teams use the Agile Manifesto as a starting point for conversation, determining what unique needs they must meet. For instance, a small, co-located team may be able to share technical information like architecture in person or using a whiteboard, but a large team that’s spread across the globe will need to determine new ways to communicate this information. 

Knowing that there’s no prescriptive formula for documentation, what advice would you offer Agile teams today around documentation?

JG: First, remember that every document you create should have value. Before you build any documentation in Agile, know who you're building it for and what they will use it for. This helps avoid waste and saves time by involving the right people in creating the document. 

When you do decide to create a document, keep these tips in mind:

Use visuals to align at a high level 

Visuals are a great way to start exploring ideas and get people on the same page. Start with a high-level vision of where you're going. You can think of this as a map. When working on something from scratch, start with a document that describes the lay of the land, communicates conventions, and helps you and your team get around the system. 

The important thing is to know when to stop. Use these visuals to explore the interaction between systems and create alignment, but don’t go overboard. There may be dozens of related scenarios—document a few to show the pattern and align stakeholders.

Create documentation iteratively

Start with a product vision. It's likely vague and fuzzy—document it in the simplest way that could work. That might be a list of bullet points or sketches on a real or virtual whiteboard. As projects progress, this vision is clarified. You discover more about the problem being solved and your potential solution.

This documentation is intended to be high-level, so try to keep it that way. Then you can add more details in the code itself. For example, a UML diagram would mention representative operations, but not specify detailed function signatures. Your map of the system helps you navigate to the details rather than clutter your vision with too much detail.

You can also take an iterative approach with self-documenting code: code with structure and syntax that clearly explains how the code works without comments or additional documentation. For example, I’ve noticed instances on my own website where the code I wrote was difficult to understand. It seemed perfectly clear when I created it, but not so clear two weeks later. I was sure someone had broken in and ruined my code! So I improve it by changing the names and structure. The next time I visit the code, it usually speaks better to me. 

Turn the work you’re already doing into documentation

Before creating any documents, ask yourself: Is there a way to create this document that’s more natural with what we already do?

Executable documentation can capture details without creating any additional work. Let me give you an example. I worked with a company long ago that had a defined process step: Document how to unit test your code. It was a manual process that became obsolete over time.

Instead of a documented manual process, try automated unit tests! This means that instead of writing a document about how the code is behaving, you write tests that make sure the code behaves a certain way. When the code stops following its specification, a test fails. With test-driven development, you naturally keep the tests and the code in sync—not to mention retesting is virtually free.

The tests become the documentation. The tests tell you in unambiguous terms how the code is supposed to work, whereas if it was written in a natural language like English, it would be ambiguous and left up to interpretation.  A document can become outdated, but the tests always reflect up-to-date information, without creating extra work. The cheapest document is the one you don’t bother writing.