Agile Development Methodology and Documentation

To document or not to document?

If Agile were anti-documentation, why is there a manifesto?

The “Agile Manifesto” was put together by seventeen software developers in 2001 – among them, Ward Cunningham, Jim Highsmith, Alistair Cockburn, and Bob Martin – and officially introduced the Agile development methodology as an alternative to the conventional documentation-driven, heavyweight software development process. It put forward the following fundamental principles:

As if anticipating that this simplicity might lead to misconceptions, the manifesto clarifies:

"That is, while there is value in the items on the right, we value the items on the left more."

Even so, misinterpretations and confusion about Agile development methodology have persisted. “Over” got replaced by “instead of” and what was intended as “It's best to dedicate more attention to the software rather than invest time in overly detailed upfront documentation” seems to have turned into “Let's ditch documentation altogether and hope to remember everything we talk about.”

Dilbert Agile programming comic

Agile myth: “Documentation is not important”

Teams that follow the traditional approach to IT projects define and document requirements in the early stages of the project. They hand them in to developers later on, who then immediately start implementing it.

And while Agile development methodology was created as an alternative to this documentation-driven development process, it did not set out to eliminate internal documentation completely. It simply placed more value on working software than on comprehensive documentation because of the dynamic nature of software development.

So there is nothing in the Agile development methodology that inherently prevents us from creating as much documentation as the project requires. There are, in fact, situations in which documentation is absolutely required. Adding user stories to the backlog, creating flowcharts, drafting wireframes, documenting client meetings – Agile simply suggests being smart about it.

Documentation should be “just barely good enough” (JBGE). Too much or overly comprehensive documentation would be a waste of time, and, as any manager familiar with the hourly rates for software developers will tell you, time is money. Moreover, developers themselves rarely trust detailed documentation anyway because it's usually out of sync with the actual code. On the other hand, experience shows that too little documentation is always a source of problems with team communication, learning, and knowledge sharing.

Reasons to invest in Agile documentation

The creation and maintenance of Agile documentation is a “necessary evil” to some and an enjoyable task for others. Either way, there are several valid reasons to invest time in it:

While all of the above may be legitimate reasons to document, we always ask ourselves the question: What's the least amount of deliverable that we need right now?

How to document things in Agile

4 rules of Agile documentation

Documentation in Agile is “living” and needs to be collaboratively maintained by the whole team. To make the most of the time we invest in documentation, we follow a few simple rules:

To make all of the above possible, a flexible, transparent, and easily accessible software documentation tools is needed. Unable to find a solution that would tick all the right boxes, a few years ago our team decided to scratch our own itch and build a better tool ourselves. As a result, today we manage all documentation using Nuclino, a unified workspace which serves as our internal wiki, sprint planning tool, and collaboration space — like a collective brain.

Agile documentation tool

When to document

The iterative delivery of working software in Agile effectively replaces much (though not all) of the comprehensive upfront requirements documentation. The idea is to keep documentation as simple and lightweight as possible, especially during the early stages of the project. So at what point is it worth investing time in documentation?

A common agile practice is to defer the creation of all deliverable documentation as late as possible, creating the docs just before you need to actually deliver them. For example, system overviews and support documentation are best written towards the end of the software development life cycle (SDLC). Essentially, this approach is to wait until the information has been finalized before you capture it.

Late Agile documentation

Another Agile documentation strategy is to document continuously. You write your deliverable documentation throughout the project, updating it as you update your code. This approach is in line with the Agile philosophy of always producing a solution that is potentially shippable.

However, because the requirements are likely to evolve over the course of the project, it takes a considerable amount of time to keep the deliverable documentation up-to-date. From the Agile point of view, this is “traveling heavy”.

In practice, Agile commonly put off writing documentation until they have time to do so, in effect moving towards the document-late practice even if they initially decided to document continuously.

Continuous Agile documentation

What to document

Examples of possible documents used in Agile documentation include case studies, diagrams, tables, and sitemaps. Here are some of the documents you might want to consider creating over the course of your project:


“We embrace documentation, but not hundreds of pages of never-maintained and rarely-used tomes.”

— Jim Highsmith, History: The Agile Manifesto

The Agile development methodology is in no way anti-documentation. It simply reminds teams to document no more than necessary, and when necessary, keeping documentation as simple as possible. The idea is to choose a format and level of detail that allow change and deliver just enough value to keep the team moving forward in the right direction.

Nuclino: Your team's collective brain


Nuclino brings all your team's knowledge, docs, and projects together in one place. It's a modern, simple, and blazingly fast way to collaborate, without the chaos of files and folders, context switching, or silos.

Try it now

Character illustration