There has been a real buzz around the Agile methodology recently. Many teams are actively shifting to this development method thinking it’s something that will considerably enhance the results of their work. Very often, teams rely on best practices or misunderstand the real meaning of famous Agile manifestos and jump to premature conclusions about the inefficiency of this development method. One of such wrong assumptions is that documentation is not an asset in Agile. In this article, we will confirm or refute this statement. To gain a better understanding of the topic, learn how the Scrum methodology approaches this documentation issue.

So the question is: “Is documentation in Agile important?”

What do we eat Agile with? The bare bones of the Agile methodology:

Before diving deeper into Documentation in Agile. Let’s first clear out what exactly Agile methodology is.

Let me present my favourite explanation of the Agile methodology: Imagine you are a chef at a restaurant. If you need to cook one dish, you will be totally fine with Waterfall’s method (Agile’s alternative). However, no chef cooks one dish at a time, and usually handles at least four courses at once. This is where time management difficulties may arise. Using the traditional Waterfall method, preparing a four-course meal would consist of chain-like tasks:

  1. First you prepare an appetizer
  2. Then you proceed with an entrée/salad
  3. Now it’s time for the main course
  4. And eventually you are all set to start preparing the dessert

So the method is clear – you don’t start preparing another dish until the previous one is ready. Sounds qualitative, right? You can focus your attention on one task without being distracted by other things.

However, what about the amount of time spent preparing the dishes?

It’s time consuming. Even if you set a deadline, it is very likely you will miss it and the whole project might even fail. You will be frustrated because you are not on time, and your guests will probably end up starving while waiting for you to stick to your plan. The overall quality will not be worth the time spent because your end user – the clients of the restaurant – will not be satisfied. It’s as simple as that.

Now let’s approach it differently: what if you divide the process not into gradual phases, but into small independent subtasks that will eventually form a project – in our case, the dinner.

In other words, if you refer to the Agile method, you can prepare all four courses much quicker, combining many subtasks at once. This will be more productive and make your guests happy.

This striking illustration, made by Philipp Schroeder, clearly shows the disparity between traditional Waterfall and Agile methodologies.

When using the Waterfall methodology, it is difficult for you to deliver the project as it is not divided into smaller parts; it is expected that the product will be delivered at once, without any revisions or changes. This is not quite possible in today’s modern, ever-changing working environment. On the other hand, when using the Agile methodology you will need to “inspect” and “adapt” if the direction suddenly changes.

Should you put the blame on Agile?

The main Agile misconceptions:

Despite the obvious values that the Agile method brings to teams, people often say: “Agile doesn’t work for me”. And obviously, they blame the Agile methodology for the imperfection of its practices.

Keep in mind, agile is first of all a set of values, not a settled and strict plan. You should be sure that you know how to adjust these values to your environment. Remember that every company has its own pace, characteristics and values. What works for some, won’t work for others! So instead of relying on best practices, try to adjust the Agile principles to your working environment. And make sure you comprehend those principles and values correctly.

There are different things that teams tend to judge Agile for. These include the following:

  •       No planning

“Responding to change over following a plan”. Many interpret this manifesto as no planning at all. This is a wrong perception. Some planning is still required with predefined tasks, budgets, priorities and principles; but this planning should serve as a guideline for the decision-making process during development. So if there is a change, you should be open to it and not just blindly follow the previously established plan.


  • Agile means less stability

Due to the fact that Agile development is quite flexible and specifications can be changed at any time, it’s often mistakenly assumed that this approach is not stable. However, according to one of the co-authors of the Agile ManifestoJim Highsmith, Agile is “the ability to balance stability and flexibility”. Indeed, product owners are free to make frequent changes to the Scrum backlog, but the sprint is fixed and can’t be affected by these changes.

  • Documentation is useless

Many interpret the Agile principle, “Working software over comprehensive documentation”, in the way that documentation is not important in this methodology. There is documentation, and it’s crucial to the success of Agile projects. However, approaches differ from traditional Waterfall methods. The secret here is to document when it is needed and include only the details that will be crucial for going forward.

Abby Fichtner summarized in her blog post:

“A good Agile team picks and chooses the management and technical practices that best work for them. (A bad one just picks a couple of practices and falsely believes that somehow ‘makes them agile’.)”

I liked this joke that I found in one of the articles on The Agile Software Engineer:

“How many psychiatrists does it take to change a light bulb? … Only one, but the light bulb has to really, really want to change.”

You should understand it this way: People with whom you work are the light bulb. Before introducing the Agile methodology to your company, you have to make sure they really want to change and that they understand the benefits it will bring them. Unfortunately, it is not an easy thing to do.

Since this article is devoted to documentation in Agile projects, we will mainly focus on explaining the last misconception that “documentation in Agile is useless”, or rather will debunk this false myth!

Agile vs. traditional documentation

I will not hesitate to repeat it again: Documentation is essential in Agile ecosystems!

The only difference between traditional waterfall and agile projects consists in the way you document processes!

Teams that follow the traditional approach to IT projects take a so-called near or serial approach to documenting, where they define and document requirements in the early stages of the project. They hand them in to developers later on, who immediately start the implementation process. As a result, any alteration to a plan caused by stakeholders’ priorities or changes in the market may threaten the well-being of your project.

Imagine your feelings then:

Therefore, the lesson to be learnt here is: it’s not really a wise plan to spend a significant part of your project time on defining and formulating the needs which you are not yet sure about.

If you don’t want to create unnecessary problems for yourself, then consider reviewing your strategy towards product documentation. Don’t make assumptions and guesses on the future outcomes of your project. Instead, focus on what you are actually sure of.

According to Jonathan BergerAgile doesn’t proclaim absence of documentation – it stands for minimizing of documentation.

In his article Minimum Viable Deliverable, he provides suggestions on how you can minimise documentation:

“All you need to do is:

1) socialise the idea that ‘less artifact can be better’ among your team, and

2) always ask the question: what’s the least amount of deliverable that we need right now? Is a high-resolution mockup really the only way to communicate that design decision? Could we get away with describing the design decision in a sentence, and then using the saved time to work through other design decisions? Or to implement some of the design?”

To put it simply, it is totally up to you whether you want to use your limited time on documenting or working on the product itself to make sure it really works. Just note that the product requirements will not be used by your end user; it will be the product itself.

You do have to create technical documentation, but only when you are 100% sure that something is not going to be changed further down the line.

What is healthy and alive Agile documentation?

Documentation in Agile has the following characteristics:

  •  Your documents have to be as light as possible

In other words, you should travel light. Or create just enough models. Think of any model as the one you will have to maintain later on. If you create models that are light, uncomplicated and not too detailed, it will be easier to comprehend and update them. So instead of creating ten models, create four. This way, you will have less work to take care of later on. It will mean you are travelling through your project with ease, with less luggage and a lighter burden.

  • Documentation should be just enough, just in time

“Agile is definitely based on JIT. You can see this in many of the practices. User stories are created when they are needed and not before. Releases happen when there is appropriate value in releasing, not before and not after. Each iteration has a commitment which is met on time. I’m sure there are other examples, but these few suffice.”Bob Hartman

Certified Scrum Trainer® (CST) and Certified Enterprise Coach℠ (CEC)

However, we say that having it “just in time” is not adequate. We also need to have enough of it. In our case, we will use just enough documentation, just in time.

We certainly don’t need documentation just to have it, but we also cannot break through with no documentation. So we stick to the “just enough” rule that is needed to be successful.

  • Comprehensively analysed

Requirements which are analyzed in a proper way are of higher priority than comprehensively documented requirements.

  • Created together

Documentation creation in Agile teams is approached on a collaborative basis. Every team member can make a considerable contribution to the document. This is important in the Agile method.

  • Accessible

If documentation is accessible, it is useful. To ensure this, store your product documentation in a place where you and your team members can benefit from it.

How are things documented in Agile?

Or let’s ask it this way: “Which form should the documents in Agile documentation take?”

Examples of possible documents used in Agile documentation include case studies, diagrams, tables and site maps. The main principle here is to clearly display information for clients and stakeholders. As long as they get your point, you are heading down the right path!

There are three types of documentation in Agile projects:

  1. Pre-project documentation

This is the amount of documentation needed to allow the product implementation to begin. It includes a short outlook of the main features of the future product and a couple of high-level architecture technical diagrams.

In no case should there be a huge amount of documentation. Let me explain why. Usually, the period between the beginning of the project and the delivery of the project may span months or even years. If you realise that change is inevitable, you will be conscious that perfect documentation is not a priority.And even if something changes – your company’s culture, legislation or market requirements – you won’t feel the pain of wasted hours documenting it.

On her Twitter feed, SupriyaLala expresses her opinion on this subject:

And now you understand why!

Greg Finzer offers a useful scale for measuring the efficiency of your requirements in your documentation method:

  1. During-project documentation – development stage

There are two types of documentation in this stage: just-enough requirements (the requirements defined in the backlog which are being used by the team during their work) and implemented system and business rules (are used as reference materials for the stakeholders and technical support teams).

  1. After-project documentation

Due to the fact that Agile documentation is done incrementally, you will have everything documented as an outcome of the project.

To successfully wrap this topic up, we recommend you to check out this video which confirms the value of documentation in Agile:

To sum up, the Agile methodology is a set of values and principles that every team should use, and they should be adjusted to suit the team’s working environment and pace. Documentation in Agile is one of the main priorities and should be approached with responsibility.