Agile means no documentation, doesn’t it?

ByPaul Henman

Somehow this myth persists: Agile means we no longer have to produce any documentation, right? Sorry to disappoint you, but that’s just not true.

If we revisit the Agile Manifesto and read it carefully, what it says is “we have come to value working software over comprehensive documentation“. It says there is more value in working software, but it does not say that there is no value in documentation – there is some value in documentation, and more importantly there is value in the right documentation.

So how do we know if we are creating the right documentation? Well, how do we know if we are creating the right software? We build small increments and get frequent feedback from our customers, so we could apply the same approach to documentation. That means we need to know who is asking for a particular document, and then understand what information they expect it to contain. One team I worked with halved the documentation that they assumed was required, simply by contacting the intended recipients; clarification of the other half meant they could deliver useful documentation which required minimal rework.

Remember that the stakeholders for your project can include Audit, IT Security, Finance, PMO, other delivery teams, and more. Their needs should be considered by the Product Owner and added to the backlog (or the Definition of Done), but that also means the work involved should be estimated. That may mean that the PO has to weigh up their value and have difficult discussions with the stakeholders about the relative Return On Investment compared to other features.

One Agile principle to bear in mind is “simplicity – the art of maximizing the amount of work not done – is essential“. Documentation doesn’t have to mean a Word file – there may well be simpler formats which can convey the information and still meet the consumer’s needs, e.g. a photo of a whiteboard or an audio recording of a conversation.

In terms of the Agile Thinking principles:

  • Know the goal: deliver relevant, valuable documentation
  • Understand the context: consider how the recipients will use the document
  • Get fast feedback: keep checking in with the document’s intended audience; test the document as well as the product
  • Use iterations: keep documentation in sync with the product; it evolves and may require rework
  • Reduce waste: simplify how documentation is produced
  • Collaborate: use the team’s combined knowledge to produce high quality documentation

(I originally wrote this for an EPAM internal newsletter.)