With apologies to Dr Seuss…
A few years ago I was asked to help out with a process review at my workplace, during which I carried out a number of interviews with some of my peers and colleagues. The review was centred around a completely different topic, but it was interesting to see how a few sentiments bubbled through regardless, with some regularity:
“We don’t need requirements now that we have Agile”
~ Actual quote
“Then the Agile Fairy made this all go away”
~ Actual quote
“Agile threw out all our documentation”
~ Again, actual quote
Now, I don’t know what this Agile noun is, but man does it sure sound all powerful and destructive! Clearly, you don’t mess with Agile, because Agile will waste you, sucka!
Doing this exercise, and talking to these colleagues, it made me stop and think about how the ‘Agile Movement’, if that really is such a thing, has treated the remarkably nebulous topic of “documentation” - both in the workplace I was in at the time, and in my wider experience in the industry.
If you rewind things back to when “seventeen middle-aged white guys… gathered at Snowbird, Utah” you might notice a few of the notes they jotted down support some of the feedback I’d gathered during my interviews:
“Working software over comprehensive documentation”
“Responding to change over following a plan”
That seems pretty straightforward.
But then there’s also this:
“That is, while there is value on the items on the right, we value the items on the left more”
Oh.
As an aside, I do wonder how many “Agile Transformations” have the Manifesto for Agile Software Development at their core. Of those, I wonder how many remember to include that caveat at the bottom.
Coincidentally - if you’ve ever read more of the Agile manifesto website than the Manifesto itself, you may have read the history page which includes this gem:
“We want to restore a balance. We embrace modelling, but not in order to file some diagram in a dusty corporate repository. We embrace documentation, but not hundreds of pages of never-maintained and rarely-used tomes. We plan, but recognise the limits it planning in a turbulent environment.”
~ Jim Highsmith
I’m sure that reminds you of more than a few workplaces, dear readers.
Getting back to my own tale, I don’t think the people in these teams I interviewed were ever specifically told to stop having requirements - I think their managers, coaches, and scrum masters just genuinely wanted to help them remove waste and BigStuffUpFront; but an unintended consequence of that was the loss of knowledge and/or quality standards. It’s easy enough to do, and not an uncommon scenario based on my own experiences and those of industry peers when it comes to ‘Agile-isation’. The balance between ‘just enough’ and ‘too much’ documentation is difficult to strike.
But there are some ways you can avoid some of this pain, and the inevitably kneejerk reaction:
“We need more governance”
~ Definitely an actual quote
When you’re documenting something, be it a process or the code that you’ve just written, I’d always challenge you to do the following:
- Prove it. Those instructions you’ve just written to deploy to the build server? Carry them out. Better yet, have someone else do it. That way you’ll find out if the instructions are correct and whether they can be followed and understood easily. Peer review of code is a well-trodden path for a reason; it puts a new set of eyes (and a different set of biases) across the same piece of work.
- Curate it. It’s not enough to write something once and then forget about it. Doing so ensures a ‘piece in time’ artifact has been created; and perhaps in days past when computers took up a room and got upgraded once a decade a 400-page reference manual might have done the trick, but given the rate of change we see in the world - let alone software - in 2019, it seems incredibly wasteful to do this. Write just enough to understand the system / process / software, but little enough to make it easy to change in future. User Story Maps might be able to help you here; Specification By Example is another good option. Others still may prefer the simplicity of a collaborative Wiki or Google/Microsoft offering. Whatever you choose, just make it easy, not a punishing and demanding task.
- Make it live. The easiest documentation - and the most accurate - is that which writes itself. Techniques like BDD (please, learn Examples before BDD, I beg you!) or self-generating documentation like Swagger are good for understanding the contracts and stories that might make up your system. Like unit tests, they’re generally not quite enough to give you a full picture by their lonesome - but they become a powerful complement to the additional context provided by a human brain.
- Don’t be afraid to kill it. One of the biggest contributors to waste is the “Wundae” approach to documentation. “Wundae, we might need it”. “Wundae we’ll get audited”. “Wundae we’ll want to know why this system behaved that way 12 years ago even if it longer behaves that way today”. If you stay with the Wundae, you’ll never free yourself from a millstone you’re attaching to your own neck. If you are due to be audited, then understand what you need for the audit and keep only that - and for god’s sake, make it understandable. If an audit is only checking for the presence of a document, not the accuracy or relevance of that document, sack your auditors or the people who hire them! If you can no longer prove it, or something has gone beyond the point of curation, you need to kill it! At the very least, put it in deep-freeze and stop confusing people or scaring them off with your reams of outdated, irrelevant documentation and process. If a process document was written 10 years ago, but nobody is following it, it is no longer the process! Archive the wiki space. Put your documents in AWS Glacier. Or if you’re brave enough, just chuck it in the skip. Get back to documenting what is relevant, and doing it succinctly.
Documentation can get a bit of a bad rap - but hey, so can the thing called “Agile”. Both can be a massive boon to any team and organisation, but only if you get people to buy in - and you can only do that by making it an improvement to their working lives, not making it a mandated, top-down tax on the workforce. No one likes reams of irrelevant or outdated text - but everyone can use a helping hand, especially if it helps them Get Shit Done.
Even the Agile Fairy would agree with that.