And I can’t either. You’ve got to face the facts – as a business analyst, no one is going to read your documentation because of your poetic commentary, your witty explanations or your inspired diagrams. At most, people might read it because they have to. So why do we get so attached to our masterpieces?
The bigger, the better?
According to closely-held tradition, developers produce code and working software; BAs product documents. Documents demonstrate to the outside world that yes, we have been doing work, as well as chatting. The bigger the document, the more work it looks like we’ve done.
But when you have a spare 30 minutes, try reading a document your colleague wrote. Or pull out a document you wrote a year ago. Even with hyperlinked cross-references, concise summaries and systematic tables, it will take a whole lot of mental re-arranging before you gain a decent understanding of the software (if you don’t have a document handy, you can bang your head against the wall repeatedly, to get the same sensation).
Software is complicated. It has rules, interfaces, data and more; and business analysts have an understanding of how it all holds together. Putting our understanding into a document that caters to different audiences invariably results in large, unwieldy documents that no one wants to read.
The record of a journey
There’s no question that the typical BA-produced document is the outcome of hard work. But it can’t be allowed to remain the defining work a BA does. Instead, I suggest the documentation should be the BA’s personal record of their journey. I say personal, because there is no ‘one correct way’ to document and these documents depend on the writers’ background, skills and understanding of the software.
We gain our understanding through long workshops, painful negotiations and endless conference calls, then distil this into something orderly and logical. But the real value of our work is our understanding, not the document itself. Looking at it from this perspective, it’s rather egotistical to expect people to gain the same understanding from our travel notes.
Dusty notes in a strange script, or bi-lingual speaking guide?
I am not advocating doing away with documentation – there is no doubt it is necessary. But when your target audience is not yourself, make sure you are communicating in the best way for them. Don’t simply point at your dusty travel notes. You are not answering questions by pointing ever more vigorously!
Currently I communicate with developers and users through a combination of conversations, diagrams, screenshots, spreadsheets and automated acceptance tests – whatever illustrates my point best. And I build up a record on a wiki page of everything I learn. It is publicly accessible, but not publicly advertised. I know where to find anything on my wiki page, but I don’t expect others to. It’s all organised and recorded so it can be picked up by someone else, but this should be treated as an emergency ‘hit by a bus’ situation not the norm.
When a developer asks a question, it’s tempting to direct them to the documentation. Yet that is like handing a foreigner a map to find your local pub, instead of just walking with them around the corner. Less time and effort for you, but a lot, lot more effort for them to get an adequate level of understanding.
So let’s concentrate on the understanding – and leave the writing to the real masters.
