When should we create a document on an agile team?

 

When transitioning to an agile mindset people invariably ask about how documentation is addressed on agile teams.  Some documents, such as system overview documentation or operations manuals, are still a valuable part of the overall solution being delivered by the agile team.  More often than not a document, such as a logical data model (LDM) or detailed requirements model, isn’t needed at all because it can be replaced with a more effective strategy or the document can be greatly simplified compared with what a traditional team would develop.  This of course is a shock to most traditionalists, particularly for those who currently spend most of their time creating such documents.

To help people understand the agile approach to documentation creation, we find that it’s valuable to describe the logic that disciplined agilists follow.  This logic is captured in the following flow chart.

Let’s walk through the decision points one at a time:

1. Do you need a document?  There is a significant difference between needing a document, perhaps to persist important information, and wanting a document.  If you’re creating the document to communicate information to someone else then you really need to question its creation.  Research into media richness communication has found that detailed documentation is the least effective strategy available to you – better options include overview documentation, video conferencing, and of course face-to-face (F2F) discussion. For a second example, many organizations still follow a traditional, documentation-based approach to IT governance and as a result many teams are forced to create documents solely because someone in a governance roles wants it to be created (or at least the team perceives that they want it).  Sometimes people want a document because they fear that the information it would contain would be lost, not realizing that the older documentation becomes the less it is trusted (see Documentation CRUFT), so in effect the information is effectively lost even when it is captured as written documentation.  The point is that many documents aren’t really needed, they are merely wanted – if the latter, isn’t it better to deal with the real people and help people to recognize they don’t really need the document after all?
2. Is there a better option?  In many cases there are significantly better alternatives to writing documentation.  For example, instead of creating a detailed written requirement specification when you follow an acceptance test-driven development (ATDD), also known as a behavior driven development (BDD) approach, you capture requirements in the form of executable specifications.  Granted, this takes a different set of skills and tools to perform, but in the long run it offers far greater value to your team than written specifications.
3. Will you maintain the document? If you’re not willing to maintain a document throughout what should be its useful lifespan then don’t create it.  If this isn’t an option, then at minimum only work on it until the point where you’re still able to viably keep it up to date.  Documents that aren’t maintained aren’t trusted, and therefore not used.
4. Do you understand what the consumer of the document actually needs?  The only way that you’ll be able to create an effective document is if you know what the audience for that document actually needs, and the best way to do that is to work with them closely.  Your goal is to create a document that is just barely good enough (JBGE), or just sufficient, that fulfills their needs and no more.  For example, instead of creating a detailed architecture model using a software-based modelling tool, co-located agile teams will often prefer to create whiteboard sketches which they leave on their workroom walls.  Yes, a pretty architecture model would be nice to have.  But the whiteboard sketch gets the job done, it is much easier to evolve, and much less expensive to create.

When an organization transforms to agile many traditional IT professionals will struggle at first with taking an agile approach to documentation.  In traditional software development, and in particular traditional IT governance, documentation is used as a crutch and worse yet a band-aid over organizational dysfunction.  We can no longer afford this and must instead be smarter about our approach to whether and how we write documentation.

For more information about agile approaches to documentation, we suggest you read the article Agile/Lean Documentation: Strategies for Agile Software Development.