The Code Whisperer

If you look at the collection and documentation of requirements for a software application as the foundations of a building, it’s easy to see why any weakness here has a major effect in the delivered item, whether functionality that can’t be implemented fully or delayed time to deliver.

Requirements gathering and documentation fail for many reasons, and each company and application will be different, however simply put you need to have business analysts doing this work that understand the business and know how to document business requirements and processes to people who don’t. It’s imperative that the business analysts write in a clear manner, clarifying complicated areas. In my view it’s better for the business analyst to spend more time producing a more understandable document than the developer thinking her or she understands it but wasting time developing in the wrong direction.

In all documents, not just business requirements and processes, I like to apply Rudyard Kipling’s epigraph from his short story The Elephant’s Child, which has become known as Kipling’s Six Honest Serving Men.

I keep six honest serving-men
(They taught me all I knew);
Their names are What and Why and When
And How and Where and Who.

This on its own isn’t going to produce fantastic specifications, but I find it useful particularly when I know the subject matter well and need to provide documentation to people that don’t, whether it’s business requirements, technical design, user manual or operations manual.

Use of peer reviews on business requirements will improve their quality particularly if it includes reviewers that aren’t familiar with that part of the business or industry.

In my experience a significant amount of the difficulties caused by business requirements (and technical design) is that the author assumes that the reader has a higher level of understanding than they actually do. In a small company with a low turnover of staff you can get away with this, but in any other case it’s a recipe for disaster. If you are outsourcing work then business requirements and, particularly, technical designs must be of the highest quality to prevent a large number of test/correct cycles.

One last point is to do with testing, in particular user acceptance testing (UAT). I would expect UAT to concentrate on testing the application against the business requirements. In a sensible development the customer would have sight of the business requirements documentation and signed them off, or provided their own “list”. Issues found in the testing should reference the business requirements and some form of reference number. If that reference number hasn’t been followed through into the technical design and actual coding, then the ability to quickly identify the location of the problem, based on the business requirement, is lost. In additional any ability to measure the time and/or cost of developing different parts of the business requirements are just about impossible. I highly recommend that some form of reference to the business requirements is carried through technical design, coding and testing.