<img src=”http://img110.imageshack.us/img110/6395/bookstackdz4.jpg” width=”538” height”892” />
Nate’s talking about functional specs.
How much doco happens on a project is one part opinion and one part “what do you want to optimise for?”. I generally find there’s a dichotomy in attitude to software documentation.
1. Definitive (aka normative, exhaustive, complete, bureaucratic, rigourous, formal). The ideal here is that everything should be covered in documentation - the docs are a snapshot of every activity, plan, and state of the project. The aim is: (a) to let you carry on unhindered if “(stakeholder/worker) is run over by a bus” for all instances of (stakeholder/worker); (b) affect payments and provide legal evidence/cover. 2. Informative (aka agile, pragmatic, informal, half-hearted). Use docs pragmatically, to help explore ideas, reach consensus, remember what we said, etc. You cannot reconstruct a project from docs like this - if everyone is “run over by a bus” at the same time, there will be a delay and a subsequent divergence in the project direction.
That’s a clear distinction - in the Informative mindset, the docs are only there to reach a better quality result; in the Definitive mindset, we’re compromising some productivity for the sake of risk management (both (a) at a tactical level, i.e. if someone leaves; and (b) at a strategic level, i.e. upper management can theoretically be comfortable about how much is exposed and how much they’ll get back as a penalty if things slow down, etc.).
Both Definitive and Informative have a range of approaches. In particular, Informative use of docs can range from none at all, up to a project resembling a Definitive project, but when you look closely, the docs are lightweight and only subject to informal reviews rather than full-on inspections and audits. They may also the use of less conventional “documentation”:
- Whiteboards
- Post-it notes
- Flashcards
- Wikis and blogs.
As an agile proponent, I’d generally favour the Informative approach, but software isn’t developed in a vacuum. Organisations understandably want to be reassured about what gets delivered, which pushes them to rely on Definitive methods. The problem here, of course, is that Definitive-style docs require an almost impossible task of pinning down requirements, and furthermore, fixing requirements runs counter to the modern organisation’s goal of being agile.
There’s obviously no one solution, but one essential ingredient comes from multi-talented people. Too often, requirements are penned by business people on the assumption that software developers are left playing with their compilers. That’s changed a lot over the past five years, and organisations will do well when they hire business people who have an interest and competency with software, and software developers (fast becoming the majority) who can empathise with the business’s needs and are actually literate as well.
(I hope it doesn’t go unnoticed that Software As She’s Developed has actually posted about software development. That’s so ‘04.)
