shutterstock_118282630“Every team needs to leave footprints. Anyone who doesn’t document their work in a project, or actively participates in helping create a persistent record of the project, is a Project Asshole.” – Principle #6 of the “No Assholes Project Team” principles 

Every team needs to leave “footprints”, or a persistent record of its work.  And yet this simple requirement causes so much grief, in both agile and traditional “plan-driven” projects.  This post covers the agile part, and we’ll look at traditional documentation in a future post.

There’s nothing in the bulk of the agile literature, starting with the Agile Manifesto and Principles, that tells people not to generate documentation. The intent of the 2nd statement in the manifesto is that you should decide to produce working software “over” comprehensive documentation, when forced to a choice. Many people read “over” as “instead of” but to my mind it is “is a higher priority than” i.e. if you have to choose between writing docs and producing working software, then choose the latter over the former.

The trouble is there is little that describes “agile documentation” in any practical detail, preferring to leave project teams with the recommendation to “do the level of documentation that is appropriate to your project”.

This lack of detail leaves projects to take very different pathways.  Sadly, ill-informed, dramatic or, frankly, opportunistic, team members has lead us to a level of documentation in projects that is sub-optimal for all stakeholders.  The reductio ad absurdum of these choices is the risible, but nonetheless common statement of  “we’re doing agile! we don’t do documentation”.

At least as far as I have found in my researches.  Despite poor documentation having a big impact, it’s not exactly at the sexy end of Agile discourse.

The reality is that all projects need some non-zero level of persistent record of project activities regarding the thinking and decisions that are going on in the project, both for now and after the project is complete. Such persistent records help us deliver the project work products and are needed for many different reasons depending on the project. Not the least reason, although it is the one with teeth, are the risk management obligations that all enterprises have, and particularly in highly regulated industries like financial services.

So the normal answer to the “what documentation do I create and use”, and where most agile texts leave it, is “the appropriate level for your project and/or organisational context”.

How do I decide what is appropriate?  Consider some practical thoughts:

1) Firstly, we need to clear the air that creating a persistent record of relevant information about a project is not being agile.  As i say in Principle #6, the people saying or promoting such nonsense are assholes.

2) the primary indicator for the creation of a persistent artifact is your professional experience.  Just come out of a big workshop that decided a whole bunch of things about the solution? Better save that somewhere, don’t you think?  the customer has just given you a whole heap of input on what they want, via a discovery workshop, a “ride on” at the customer site or similar.  I’d say that calls for being saved, whether original documents or project team analysis.

3) There are several practical indicators that will arise in the project about what is important: people keep asking the same questions? Create somewhere to point them to to find the answer.  Teams are forever diverging from key architectural decisions? don’t have even the high level architecture written down?  better fix that.    Team discussions are made difficult or inefficient because people cannot remember the names of components, technologies, even people.  Get something down on real or virtual paper so they can refer to it as they debate.

4) There are (at least) four key questions that we should consider, even as a fleeting thought, before you create anything:

a) “who is the audience for this persistent data”? tailor the info appropriately. the more context and background the audience has, the briefer the document can be, and vice-versa

b) “what is the purpose of the document”? are we recording a decision that we can point to in a day or week (an hour) to give direction to a subsequent action in the project? are we preparing material to hand over at the end of the project to other participants? are we defining an integration across multiple systems and teams that defines how these are going to work together? again the “document” needs to be fit for that purpose and no more

c) “what is the quickest, least effort form in which to capture this for the target audience / purpose”? in most cases it comes as a set of bullet points or a diagram. but there’s absolutely nothing wrong with screen shots of whiteboards, as long as they are legible, and it doesn’t need a full re-rendering of that diagram to make it legible, e.g. some notes, callouts or legends may suffice.

d) “over what organisational, temporal and spatial area does this information need to persist”? something that needs to be provided to remote participants for a period after the project is complete will have a completely different set of characteristics to something that just needs to last until the next sprint retro.  Think in terms of inter-team, intra-team, organisation and external scopes for organisation.  Likewise think in terms of inter- and intra-sprint, within project and post-project.  similarly with spatial or geographic.  don’t forget that there is a big step up in requirements just moving that spatial scope from within your team area to across the floor or on a different floor.

5) The persistent record needs to be fit for purpose for its ultimate users. if you are a developer and the audience is an end-user then you can’t generate it the same as you would to another developer. in this matter, sadly the user has the final say. i say sadly because a) sometime generators of documents don’t like giving other people say over what they do, and b) this means that we are open to being asked for “standard documents”, like BRD’s etc, if our user isn’t very far up the agile learning curve.

I think that you probably see a pattern here. There’s little here in principle that isn’t already part of the agile mindset: customer-focus, efficiency and fitness for purpose, and not being driven by any fixed mindset about what is needed.  This is the agile mindset over all deliverables.

So, we can see that there is nothing special about “agile documentation”. It’s just another normal component of delivering a project in an agile way.

Keep this in mind next time someone says “we don’t do documentation”.  Every agile activity follows the the same pattern: fit the deliverable to the purpose, involve the user, be efficient and quick, and don’t let anything drive the form of the outcome other than its use.