The Art of Requirements Writing

The one area where I see companies could improve and make a HUGE impact on their development is in Requirements Writing. Most companies err on the side of too little or, unfortunately, way to often, none.

The biggest problem we see as a result of insufficient requirements is almost always scope creep, meaning that because there is no baseline, features just keep getting added to a release, and the result often is that the release never gets released. The other common problem we see from non-existent or insufficient requirements is that what gets implemented is often not what was intended, and if by chance the implementation is done correctly, it has taken a lot more work, time, and interaction than it would have otherwise.

The other side of the coin is perhaps more interesting. It’s rare, but sometimes we see companies that put too much in their requirements. I think this fear is why some companies don’t do anything at all – they don’t want to spend eons writing reams of paper and analyzing every detail. Rightly so, it’s a waste of time. The kinds of things we see in this area fall into two main categories of content and formatting.

As far as content, the biggest error is trying to turn a Requirements spec into a Design spec, meaning that instead of detailing what needs to be done, the requirement details how it should be done. Now there is a place for this, but it’s not in requirements. Specifying the how in requirements really limits the options and almost always results in a sub-optimal design. If the requirements are being written by a business analyst, as good as they are, they are not usually experienced architects or developers. Even if they are being written by a developer, the benefit to separating what from how allows the developer to look at all the requirements as a whole and in a separate thought step design the how in the best way taking everything into account, not just one requirement.

As far as format, the least useful way to write requirements (and ironically, probably the most difficult way) is in paragraph or prose form. There’s just too much content, and the important points are not easily identified and digested. Additionally, it takes an additional step for every user of the requirements (development, QA, Tech writing) to get the relevant information out. Obviously Use Cases are a tried and true and very effective method, but even bullet points (as long as they contain enough information) are preferable. The information contained should include the user entries, the results, any exception or error conditions and any other affects of the feature, easily and quickly captured in a bullet point format without any extra text to wade through.

Bottom line – well written requirements are HUGELY helpful to everyone in the development process and will make a great impact on getting your product out quickly. I’m sure there are offenses I’ve missed here. What other kinds of things have people seen??