Is any documentation truly essential?

A crucial feature of migrating to Agile is identifying the irreducible documentation needed to support the process. For many Agile practitioners the very notion of a fixed documentation suite will raise their hackles, but there are many stakeholders, not all of whom are directly involved in the delivery process, but all have interests that must be taken into account.

To name only the most obvious, there are four general classes of stakeholders, each with their own distinct information needs:

  1. The delivery team itself
  2. The business.
  3. Users.
  4. Operations, compliance and support

These groups are already poorly served by real-world waterfall processes; the risk is that Agile’s understandable and largely justified desire to take an axe to the great mass of pointless documentation will result in them being served still worse. So…

The delivery team

Well, obviously. And generally speaking the Agile assumption that there is, by default at least, no need for internal project documentation, holds good. Why would I need to write down what I can tell everyone in a tenth of the time? Why write down anything at all if its lifetime is likely to average maybe 15 days?

But less obviously, is it in fact the case that they need nothing? In very simple projects, yes, it usually is, but in a more complex programme – for example, a dozen Agile workstreams flowing into a common integration/release cycle – they may well need a good deal more. In such a situation, the Product Owner and team lead is likely to be unavailable quite a lot of the time (doing programme-level duties at meetings and forums) and when they return to base, unable to convey everything by word of mouth.

Then the standard criterion for documentation should apply – fitness for purpose. But in a delivery process of any significance (and presumably all your deliveries are significant!), that rule is unlikely to result in there being no documentation at all. Add to that the other reasons why documents are typically useful – because your work is especially innovative, organisationally complex, heavy with technical or regulatory content – and ‘pure’, document-free Agile starts to look a bit thin. In general terms, we should absolutely never create more documentation than are strictly needed, but don’t assume that the minimum set is zero, even for the delivery team. That is often wishful thinking.

Business stakeholders

Yes, having a properly empowered Product Owner should allow you to dispense with almost all external review and approval (and so with a lot of documentation that normally circulates around many organisations), but even in the most empowering environment there are likely to remain yet higher level reports. Much as most of us would like to dispense with this too (why don’t they just have faith in us?), ultimately projects exist because they serve the interests of the organisation as a whole, and someone Up There really does need to know what we’re are up to and how well it’s going. So there is all but bound to be some form of reporting.

However, taking a constructive approach to this can also encourage those to whom reports are normally due – PMOs, line managers, HR, finance, senior stakeholders, etc. – that they don’t really need the detail they are probably accustomed to. especially if you’ve established fa track record of delivering real working solutions within a matter of days, it’s hard to get too insistent on interim reports. Reporting strictly by exception is the starting point, as it is that, rather than no reporting at all, which is the true corollary of empowerment. A second key change that is relatively easy to get through is reminding the people you’re reporting to that the reports re reports – not requests for instructions or approval. .


Under waterfall, users were often the Cinderellas of documentation. it wasn’t that they didn’t get what they needed – manuals, training, etc. – it was more that they were practically never asked what they wanted in the first place. One of the big positives about Agile is that developers work actively with real users to define, build and verify delivered solutions. However, this isn’t all you need to think about.

Broadly speaking there are 3 levels of user documentation:

  • Training.
  • Usage.
  • Reference.

The users who actively participate in Agile development are typically very expert. As a result, their opinion about what kinds of documentation you need to deliver alongside your code – or whether you need any at all – may be a little different from, for example, an occasional, newly inducted, transferred or promoted user. So you should probably look elsewhere for details on what user documentation is really need. Of course, a lot can be done by on-screen documentation, but again, your expert user is unlikely to be the person you want defining or agreeing that. Neither is your Product Owner, the local users’ manager, etc. At least get a new user in – they deserve as much.

Operations, compliance and support

These groups are also likely to need solid documentation. In many organisations the needs of operations, service transition and support teams are already poorly met, and Agile is unlikely to do them any favours. Nevertheless, it is crucial that their needs are met, and these needs go far beyond touching base with them or even having them represented on the project. They will spend far more on the delivered system than the developers, and the better equipped they are to manage the delivered solution, the better for everyone.

Operations, compliance and support work will make up the great majority of all but the most superficial IT projects (e.g., throwaway web pages, transient rate updates, etc.), and their needs are not only substantial but also penetrate deeply into the heart of what is being developed. They all need to be consulted about the original needs, and their limited availability may mean that the information they provide will come in the form of documentation. They may also work to standards that have legal, regulatory and contractual standing (e.g., SLAs) or reflect corporate strategy (e.g., ensuring sustainability). So they all need early warning of what, functionally and technically, is coming down the track, they all need to know what exceptions have arisen as the original requirements/stories/backlog were progressively shaped and re-shaped, and they all need to be aware of the schedules for release. This will typically mean documentation – less than in the past, but still quite a lot will be value-adding and inescapable.


So what does this all add up to?

  1. There is a very great deal of documentation that genuinely can be thrown away – and good riddance. It adds nothing but dead weight to the project and should be discarded whenever possible. Which is remarkably often.
  2. Quite a lot of other stuff needs to be transformed. It is very likely that groups such as administrative functions (PMOs, HR, finance) will have to change the way they think about projects and how they are reported (if at all), but it is unlikely that they will abandon reporting altogether. Nor should they. Likewise for business stakeholders – they need to assign real power to Product Owners and the users representing them within the project, but they are unlikely abandon all visibility. And given their responsibilities, how wise would it be to do any such theing?
  3. Finally, there are those who will need what they have always needed. But if you don’t give operations and support what they need, they probably won’t notice much: by and large they weren’t getting it with waterfall either.

By |2018-08-01T13:15:21+00:00Monday, May 24 2010|Categories: Agile, All, Documentation, Process and method, Project management, Quality, Stakeholders|0 Comments

About the Author:

Chief Architect,

Leave A Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Want to do more than just build systems?             
error: Agile201 is wholly copyright and copy-protected.