Skip to main content
  • The Wellington City Council (WCC) wanted to deliver quality outcomes without breaking the bank. Find out how Planit’s fast and flexible resources helped WCC achieve this goal.

this is a test Who We Are Landing Page

INSIGHTS / Media Coverage

To Document, or not to Document: How Much Documentation should Teams Produce?

 12 May 2016 
INSIGHTS / Media Coverage

To Document, or not to Document: How Much Documentation should Teams Produce?

 12 May 2016 

Knowing how to create documentation is something I am often asked about, having worked with many teams.
It is also one of the most challenging aspects of Agile that teams struggle with, particularly coming from traditional projects. The answer to the question of how much documentation to create is – “it depends”. This article will not give you the magic formula, but hopefully provides some guidance which can be applied with a bit of good old common sense.

Starting at the high level, here are some dependencies to consider regarding the amount of documentation

More documentation
  • Newly formed teams – may be required if levels of trust have not yet been built
  • Compliance driven project - need to provide high levels of traceability to individual compliance requirement
  • High turnover of staff - conversations cannot be transferred efficiently to new staff without providing it in writing
  • Non collocated - sharing any information face to face can be a challenge
Less documentation
  • Well established teams – collaboration patterns established
  • No requirement to meet external standards - informal conversations are good enough
  • Stable teams - The IP is retained in teams heads (although this may be a separate issue)
  • Collocated - All information is shared across the team
Start with high level stories

There is no point in writing any level of detail if the team is going to get regular feedback and potentially move in another direction, as some of the lower Business Value Stories (or epics at this stage) may never get worked on. While there is nothing more soul destroying than seeing all your hard work not being delivered, it is important to think of these stories/epics as placeholders only. These may have been requirements at some point in time; however with the fast feedback loops in Agile, things can change rapidly. Ideas that seemed good at the time may now have little or no value.

Understand the required quality attributes

An often overlooked area when capturing user stories are the non-functional or quality attributes. The standard ISO 25010 provides a good description of these attributes which can almost be used as a checklist. Certain words that people use when describing requirements, which should trigger further questioning are easily or quickly. These then need to be converted into non-functional requirements with testable acceptance criteria.
Let’s take these quality attributes and look at them in further detail:

  • Easily: alerts you to the fact that there is likely to be some useability criteria, or at least to remove this wording if this is not the case. We could be talking about how the use of the application is first learnt. Is the user able to navigate through in a logical way? Can they understand what to do if warning messages are displayed?
  • Quickly: implies a performance attribute requiring further questioning to find the expectation of the user. There may even need to be some expectation setting and negotiation, it is good to start these conversations early.

Non-functional requirements are worth documenting completely so they can be discussed at the start of the project and continuously factored into the product throughout the build. Non-functional attributes are often missed until well into the project, until they become more difficult and expensive to retro-fit. These quality attributes are also the ones that may cause dissatisfaction with your customers if they are not considered before the product is released to production.

Manage documentation within teams

An area where documentation is important is where multiple teams are working on an application. Decisions made by one team could impact others that integrate with it or use a shared service. The interconnected teams need to agree an appropriate level of detail that meets both the team’s needs, without causing too much of an impact on the team velocity by requiring documentation in minute detail.

Challenges with team documentation

When teams initially move to Agile, difficulty is often encountered when judging the amount of documentation needed in order to get started. Using the traditional mindset of wanting to document as much as possible before handing it over to the team, the Product Owner or BAs might feel challenged if the rest of the team start to ask them questions. It might feel like they have not done their job properly and correct level of detail has not been defined if there are still questions.

Education may be required to encourage questions, and collaboration to elaborate on lower level detail requirements that are part of the Agile process. BAs can spend too much time going into detail on all the stories, which sometimes slip into providing solutions, when in fact they are a placeholder for further conversation when stories are about to be consumed by the team.
The above is not only a challenge for the BAs but also developers and testers new to Agile. Being used to high volumes of detailed requirements which they are not going to get can be an uncomfortable experience having come from a traditional background, and a balance needs to be struck between team members. Just enough documentation to get started, but enough to provide some security in the level of detail even if this is only perceived. This should naturally become less as the team matures.

Capture information in different ways

I like to see teams capturing information in different formats, rather than pages of text. One technique for recording lots of discussion in a summarised format is the mind map, allowing conversations to flow, providing an easy display of information and outlining important relationships. We all know that a picture can capture a thousand words. Drawing diagrams of progress flows or mock screens and pages can help consolidate team news and promote questioning. Someone in the team just needs to convert this into a digital form, which could be as simple as taking a photo and placing this in a shared project space, such as a wiki. The level of documentation is a likely topic to appear in retrospectives. This can easily become something that is
set at quite a large volume, remaining like this unless it is challenged. Keep this in mind when thinking about
fast feedback loops and striving for continuous improvement. Only detail information when it is about
to be consumed and not a lot of upfront documentation. Just in time at just the right level of detail.


To answer the question about how much documentation a team should produce, unfortunately
there is no rule which says ‘a certain size fits a particular situation’. Even when you find the right volume, this needs to be challenged as the team matures, and the amount of documentation will eventually move to ‘just
enough’. There are some ideas contained within this article that should help you get started and can be used within your retrospectives to continuously improve in this area.

Leanne Howard

Business Agility Practice Director

Embed Quality in your Agile Delivery

No matter where you are on your Agile transformation journey, we offer a broad range of consultation, assessment, training, and coaching services that enable your teams to deliver better outcomes faster, embed quality in every iteration, and adopt 'shift left' practices.
Find out how our Agile Quality experts can help you understand your Agile maturity and fast-track your journey to Agile success with quality embedded throughout. .


Find out more

Get updates

Get the latest articles, reports, and job alerts.