discovery based learning

Agile core values: working software over comprehensive documentation

Documents Enclosed

Documents Enclosed, maybe. Anyone want them?

As humans, the best way to learn about something is by discovery. Discovery based learning and, especially kinaesthetic learning (fiddling with things in the physical space), is fundamental to our understanding of the world around us. Imagine a pre-school child. They cannot read, no matter how advance their parents think they are and will instead learn about the things around them by playing, poking, fiddling and, sometimes, breaking things.

As a man, I learn best about something by ripping open the box and playing with the content. Rarely will I pick up a manual, Only when I’m very stuck will I rummage through the packaging looking for it, but more often than not, they’re dull, badly written with difficult diagrams and just make the whole ordeal of finding out how something works more, not less, painful. (If I can’t find out how to make something work, I try not to blame myself, it’s nearly always the fault of the product. No, really, it is. Read The Design Of Everyday Things and you’ll understand!).

As a user, the same thing applies. I’ll find out how your software works by playing with it and, usually, online software doesn’t come with a manual. Some come with help pages, but not often on HOW to use the site, just the site functions. There are some great websites that slowly engage their users by offering functionality that doesn’t require signing in and making the whole signup process part of that engagment (anyone who has used Picnik will know about that).

As a product designer (read; interaction designer, UX designer, designer, whatever) I’ll learn about how my users interact with my product by watching them use it. This is key to my understanding of the user experience and how to make it better.

As a business owner or customer, I can play with the software that my engineers have created from some of my half baked ideas and, importantly, some of my users’ half-baked ideas in order to see if it’s what I wanted, if it’s what I thought I needed or even if it’s how I described it.

None of this is possible with half a pound of paper that someone (or someones) spent six weeks slaving over.

The trouble with documentation is that it’s easy to mistake a big wad of requirements for the sum total of features required (the clue is also in the name). If you give an engineer a requirements document, they’re apt to go away, spend some time building what the specs require and assume that, given the size of the weighty tome, everything they need to know is contained within it’s black and white, mono-spaced pages.

Of course, in most instances, they’d be wrong. Once they show the “finished” product to the customer, there will more than likely be a whole slew of changes, one or two “hmm, that’s not what I meant, you’ve misunderstood” and maybe even a “no, this is useless now, the market has changed and our users want X, Y and Z instead”. This usually results in a pissed off engineering team.

So, instead of comprehensive documentation, provide working software to your customer and do it frequently. They can provide feedback straight away, steer the engineers in the right direction if they’ve gone off course, or change their minds frequently once they’ve seen the software. Delivering working software frequently will create transparency on the state of the product and transparency leads to trust. Trust between your customers and engineers is so massively important to the success of any project you should take every opportunity to cultivate it.

On top of trust, you have satisfied customers who have spent money and, lo and behold, have been given something of value. You’re getting the right business value with constant customer/stakeholder alignment and you’re getting it faster than if you’d just created documents. If you’re working in iterations and creating potentially shippable software, you’ve created value. Of course, there’s value in documentation, you just can’t sell it yet. ;)

Still, this doesn’t mean you should never create documents. If you’re working on software for a heart monitoring machine, then you’ll need to be careful and so create documentation to meet due diligence requirements (and, to make sure your software does EXACTLY what it needs to), if you’re required to create documents for legal reasons or maybe you’ve got an exceptionally difficult set of algorithms or data bindings that you should capture, that’s OK too.

Just don’t create documentation for the sake of it. Working software is always more valuable and far, far more useful.

One of the principles of Agile is that we measure our success with working software. How much software is working? That’s how successful you are. How much documentation have you got? Who cares, I can’t use or sell documents (unless of course I’m selling documents).