Working software over comprehensive documentation – one of the tenets of the agile movement that was enshrined on the agile manifesto over 10 years ago. But it is often hard to convince grey-haired old men carrying sharpened stakes (aka the stakeholders) that when things go wrong, the safest path is NOT for someone to look up the very thick and comprehensive ringbinder your BA team created at release time, find the page with that code on it, and fix it.
Back in the day, a whole industry grew up around documentation and manuals for software development projects. You could even get a job as a ‘technical writer’! I’m glad to say we don’t hear much from those people today, but I have no doubt they still exist somewhere in the land of waterfalls. Plenty of people still make loser manuals, as Mary Poppendieck is wont to let slip. And between James and I, we must have tried ring binders, post-it notes, wikis, white boards, powerpoints, omnigraffle, photos, blogs, twikis, email, text files… just about everything except stone tablets.
Luna hero Donald Knuth would tell you that to some extent the software should be its own manual (aka literate programming) – if fortune smiles upon you, it will be able to be picked up by a later developer and sorted out, based on the use of well-known programming techniques, sensible structure, and the occasional comment.
Architecture is another matter again – agile talks about it being a shared responsibility, about anyone being able to draw it on a whiteboard at any time. Good principle, but things can get quite complex at times – most people don’t want to know everything, just where the dragons be.
Alistair Cockburn made an interesting point at Agile Australia 2011 – that principle #1 of the agile manifesto was about the importance of face-to-face communication, and principle #2 was around minimising documentation. What if we combined these two ideas? In a world full of Youtube consuming, non-reading, video-savvy people, surely a short piece to camera was the next best thing to having the creator of a piece of code on the spot to consult?
So, from a small scribble in my To Do list, was born a video documentation project to take some risk out of moving the Lonely Planet website with a new team being started up in London – 18,000km away with all new people.
The idea was simple – 10 videos, less than 5 minutes each, hi-res with a Flip camera so the whiteboard drawings could be easily seen, and the focus being on pointing out the dragons. Explain the interfaces, where test coverage was weakest, some detail around the databases (recorded brilliantly with a screen grab tool by the DBA) and a great lesson in all the gotchas. The lowest tech thing we could do was label them well, stick them on a USB drive, and ship them to London.
Great idea for release notes, progressively recording improvements to code. A now out of production Flip is only going to cost you a couple of hundred dollars on eBay.
If nothing else, it might avoid the kind of developer comments we once found in some packaged software code -“what kind of f@#$tard wrote this? I have no idea what this is for!”
Give it a try with your iPhone and let us know how it goes.