Quality documentation for your developers
I was in Diana Mounter’s presentation on Friday about “Custom vs CMS” website development, talking about functional requirements documentation and got me thinking about the level of quality of documentation business analysts, system architects and analyst developers produce for use by the development team. I believe the onus is on those people to ensure that the requirements documentation is of a standard that is readable rather than writing crap and just expecting them to figure it out. Unless those developers are making extensive use of frameworks and possibly using Ruby on Rails the chances are each develop will write thousands of lines of code. The last thing they need is to be muddling through badly-presented text in the requirements document - they deserve better. And it can be as simple as the presentation … although hopefully the actual requirements themselves are of high quality, well thought out and explained.
Take this sample requirements document:
And now with just a few changes, presentation and formatting tweaks, how much better it is:
Optimise the development experience and it’ll reflect in the final product. Now, obviously this hastily-assembled sample could do with better-worded requirements, but it’s just an example.
On a side note, thinking about matching requirements and features to a bug-tracking system. One day I would love to see the tracking system configured so the “modules” or “components” drop-down list at least vaguely resembles the features and modules of the system …
September 28th, 2008 at 12:31 pm
: On a side note, thinking about matching requirements and features to a bug-tracking system.
Absolutely yes; I’ve been leaning more towards a trouble ticket system for this very reason. If each requirement is reflected with a ‘trouble’ ticket, it’s easy to see the original requirement, what someone did with it during implementation, and the later UAT feedback from the client.
September 28th, 2008 at 7:11 pm
This is an excellent sample, even the CSS styles are specified.
I would like to suggest The technical requirements specification in web projects as a complementary article.
September 28th, 2008 at 10:08 pm
That is one of those *ding!* moments. That makes so much more sense. Gotta try that out.
Raena: I do that already, and it rocks - it also gives you an audit trail - you can easily see what has been implemented already, and when things change or a requirement was quite right, it is easy to manage.
October 1st, 2008 at 10:20 am
Smashing stuff, wish stuff like this was always so heavily documented by clients..
October 3rd, 2008 at 6:52 am
I’m working through a 400 page specs doc at the moment (to approve it) - frankly I like your approach better!