I have seen my fair share of templates. For each document a business systems analyst is expected to produce, there is a pre-made formula. At first, I thought it was like colouring in – you get an outline, you colour in between the lines and at the end, you have a masterpiece. It quickly became apparent that this approach wouldn’t turn me into the next Picasso.
The problem with the way most templates are used is that a single template is designed to encompass a humungously broad range of vaguely related scenarios. Matching this vast, vague template beast to any specific focused software development project I have ever worked on is a painful exercise both for the writer and the reader (on the off-chance your audience tries to read it). Software projects vary substantially: one project may be process focused; another may revolve around the UI; and, yet another may involve purely back-end processing. Sometimes people forget that templates are intended as a starting point, a guide or cue and should never become a rigid exercise of filling-in a form without regard for the purpose of the writing in the first place.
A much better approach is the (seemingly) lazy one – document the least amount you can survive with. Despite stereotypes about business analysts, we don’t have endless amounts of time to write tome after tome, so if no-one will read it, I’m not writing it.
So how do you know what is enough? For me, this depends on the content and the people I’m writing for. To describe a process, a diagram is often sufficient. For complicated business logic, written (or executable) rules may be more effective. When my target audience is a team of senior web developers, I’m not going to detail obvious web validation, it’s a given.
I was recently asked by a developer if I could provide two wireframes for each screen. One ‘clean’ one which showed the controls, the other also showing the controls, but annotated with rules and validation. I have no problem with this. For me it doesn’t make much difference if I am communicating these rules in a table, as notes or verbally. As long as my audience gets the picture, I’m happy.
Tags: documentation
hey mel,
like ur post, very true about the relevant documentation not the excessive documentation in business analysis space. i am some requirements of my own will be sure to keep this mind…