The Kernel Journals 4: A Cure for Document and Template Addiction

The Kernel Journals 4: A Cure for Document and Template AddictionMany organizations have achieved a degree of process maturity (reliability, discipline, consistency) only by paying a very heavy price – they have become addicted to documents and document templates.

Unfortunately, it can happen all too easily. Most processes end up being document-centric even though they never set out to be so. They start by offering useful process guidance on how to progress the project in a controlled way, in the form of a set of activities, each of which is defined in terms of the artifacts it produces. Most artifacts are documents of some kind and the process helpfully comes with templates for each document – a template is better than having to start with a blank sheet of paper, after all. The project milestones we need to pass through are evidenced using the documents, and the whole thing hangs together nicely.The problem is that in practice the documents rapidly become ends in themselves. The way to progress, after all, is to fill out the templates and get someone to agree the results. To make sure the documents are in good shape, they are reviewed for completeness (i.e. no sections of the template left empty) and correctness (no typos or spellos), and are reworked and re-reviewed until they are 100% complete and typo-free. Even attempts at declaring that we are “iterative and incremental” by adding statements to the documents declaring them to be “living and evolving” doesn’t seem to help our case - our world now revolves around documents and it takes us weeks or months to get enough agreement about the vision and the plan to even start the real job of writing some software.

But going back to "coding and hoping" that what we’re building might be what was really needed won’t hack it either. We know there are certain pre-requisites to “sprinting” – like enough handle on the vision (problem, stakeholders, needs, solution scope), technical approach and platform, and enough of a credible release plan for it to be right to make the investment in letting a fully tooled-up development team loose on the job. But how to make sure we are “OK to go” without getting into the document review and approval time trap?

What we need is a simple way of characterizing what state we need to progress the different aspects of our project to (e.g the problem is understood, the release is scoped and the release milestones are agreed) without prescribing exactly how we should evidence it. Frankly, any old evidence will do as long as the people that need to agree what needs to be agreed are happy to agree it on the basis of whatever it is they have seen.

So, once again our kernel domain model comes to the rescue, with its simple characterization of the key things that all projects need to manage (such as the project, the requirements and the team) and the states that we need to progress them through (such as “project milestones agreed” and “release scope agreed”). By adding a few simple assessment criteria to the states (such as “the needs of the key stakeholders have been captured “, “the next release point and release cycle milestones have agreed target dates”, “the scoping requirements have been prioritized for the release”), we can rapidly agree what needs to be agreed without worrying too much about precisely about how it is documented, or whether it is totally typo-free.

And this is more than empty theory – I have seen software projects in mature development shops cut their lead time (from project start to starting the first “sprint” to develop and demonstrate increments of production quality code) from weeks or months to just a few days, without losing the ability to progress in a controlled way through the quality gates of the governance framework within which they operate.