Debate #2: Do you need Documentation in Agile?

Welcome to the second blog in this series of “20 Controversial Topics of Debate in Agile“. The second installment focuses on another myth about Agile: the incorrect belief that there is no documentation in Agile.

Myth: There’s no documentation in Agile

stacks of paper, representing the levels of documentation on agile projects

There is a misconception that there is no documentation in Agile. This just isn’t so. However, the level of documentation can vary depending on the type of industry you are in, and the type of work you do.

What does the Agile Manifesto say?

According to the Agile Manifesto, we value:

“Working software [or product] over comprehensive documentation”

Agile Manifesto

We value the things on the left more than the things on the right, but that does not mean that there is no value in the items on the right.

Situations where more documentation will be needed

Highly Regulated Industries

Image of a blood pressure monitor and medicine, related to highly regulated industries that will require more documentation when using agile

Regulated organizations require more documentation. This includes industries such as:

  • Healthcare
  • Insurance
  • Finance
  • Government
  • Any industry subject to audits and compliance

Large Traditional Companies

Large, traditional companies tend to be slow movers in adopting practices such as agility. Many organizations still have hoops to jump through to deliver projects.

In these circumstances, you will often find a Project Management Office (PMO) at work, monitoring and controlling all work and work products. If they have a tollgate system (even if you are using Agile for delivery), you may need to fill out required documentation.

Situations when less documentation will be needed

Non-regulated, but complex work

When working on complex work, such as software development (not at an industry listed above), the level of documentation will still vary.

image of a computer screen with programming code on it, demonstrating complex work for which there will be less documentation in agile

That said, there’s another important concept to understand about Agile, which is:

maximizing the amount of work NOT done”.

Agile Manifesto

This means that you only work on the most valuable items until they are complete, and don’t spend time on things that have not been prioritized.

Innovation or experiments

Sometimes you just want to try something out. You want to experiment – throw spaghetti at the wall – until you find something that sticks. Agile is great for doing this. You can run one-day or one-week sprints, giving yourself a timebox to determine what’s possible (or not).

In experimental or innovative situations, you may have next to no documentation. You may only have sketches on a napkin or drawings on a whiteboard, and whatever doesn’t work gets discarded.

When you have just enough

image of a clock on a desk representing the concept of "just enough, just in time" in agile
Just enough, just in time

Agile suggests you have lightweight documentation, not necessarily NO documentation. So, in following the last section, you want to get “just enough, just in time”. By waiting until the “last responsible moment” to get the details of your requirements, you ensure that you haven’t wasted time on things that may never be developed.

What “just enough” documentation looks like will depend on the needs of your developers. Some will need more than others depending on their skills and experience. You also want to make sure that any supplemental requirements models are included so the user story and acceptance criteria meet your definition of “ready” and are “suitable” for development.

So, who wins the debate?

It depends on the context of your situation. If you are in a regulated industry, you will likely be required to provide more documentation. If not, you can get away with a lot less documentation, but that doesn’t mean there won’t be any. Regardless of the situation, do what is best for your team under the circumstances, and ensure that enough information is captured for anticipated needs.

What do you think?

I’m very curious to know how much documentation you produce and what type of environment or industry you work in. Drop me a line and let me know if this debate aligns with your experiences – I would love to hear about it!

And if you somehow missed my first blog on this topic (impossible, I’m sure!), and want to know what is coming up next, here are the topics I will cover in this blog series:

  1. Can you use a Sprint 0 in Agile?
  2. Do you need Documentation in Agile?
  3. Is there a “right” way to write User Stories?
  4. What’s the best way to write Acceptance Criteria?
  5. How long should your Agile sprints be?
  6. Should all your Agile teams be run the “same” way?
  7. Which “flavor” of Agile is best?
  8. Can agile co-exist with waterfall?
  9. Story Size – What’s an Epic, Theme, Feature…?
  10. Can the Scrum Master be a team member, too?
  11. Can distributed Agile teams work?
  12. How should you estimate in Scrum & Agile?
  13. Is it OK to add items to the current Sprint?
  14. How should you manage your Agile backlog?
  15. Can an Agile team have more than one Product?
  16. What is the optimal size for Agile teams?
  17. Should Agile teams stay together?
  18. How should you handle defects in Agile?
  19. Can a hybrid of Waterfall and Agile succeed?
  20. What are the official roles on an Agile Team?

Resources: