Perspectives
Four Pitfalls of Poorly Crafted Requirement Specifications
In a world of ever-increasing demands and quick turnarounds in delivering software features and enhancements to the end user as fast as possible, it is very easy for development requirement documents to become susceptible to bad habits. These bad habits can lend themselves to rushed timelines, development errors, re-work, a slower time to market, and increased cost. An effective requirements document should serve as an explanation of what the user needs, a checklist of items to include, and a guideline for the Quality Assurance (QA) team to build test cases. It should also alleviate most follow up questions between the development, product, project, and relationship management teams and the end user.
Four things to avoid when crafting your requirements documents to ensure a seamless transition from a user’s request to a completed piece of software:
Assume a requirement is obvious or omitting requirements.
- What may seem obvious to the end user may not be to the developer. It is necessary to be as granular as possible when digging into the details of the specification document. Any omitted details can cause a roadblock for the developer or leave the requirement up to the developer’s interpretation. This can result in a different outcome than what was expected by the end user or cause functionality to be excluded and must be added in later thus increasing the time to market. When writing out specifications it’s best to take the approach of “writing out directions on how to make a peanut butter and jelly sandwich to an alien.” Step one: unscrew the lid off the jar of peanut butter…
No standard template or consistent format exists.
- Just as a story reads left to right top to bottom, a developer should be able to read through the requirements document in a format that makes sense. A well synchronized layout should take the context into consideration where one requirement might shed light on another requirement. Requirements should be placed in a hierarchical structure so the developer can start formulating their plan as they read through. Another benefit of a standard template is when a developer must refer back to the requirements document they know where to look to answer the question they have or the item that needs more clarification. The developer gets accustomed to a particular format and can quickly identify the section of the document that has the answer.
- While standard templates are useful and needed, they should also not be blindly followed. If the requirements template your firm is using is geared towards a report, but the end user is asking for a feature, don’t try to fit a square peg into a round hole. If the sections of the document do not fit the item being built simply remove it or mark as N/A as opposed to trying to fill the space with unrelated subject matter that lends itself to more questions than answers.
Omitting samples, mock ups, or test cases.
- In completing requirements specifications, it is a good idea to include a mockup of functionality or a sample. This serves to tie a bow around a requirements document and sync up the end users and developers shared vision of the development ask. For a functional piece of software, a mockup or diagram of how the software should behave, or for a static item, an existing sample or images tell a story that can sometimes be lost with words only. It’s best to put this at the end of the document so the developers can formulate their own ideas and picture how the new development will look and see how closely that pairs up with the end user’s perspective. Lastly, including a few test cases that a developer can quickly run through to test core requirements prior to handing over to the Quality Assurance and Testing team can be a massive time saver as opposed to discovering a potential issue downstream, which then needs to go back to the developer to fix.
- While these are all good examples of details that will assist the development team, one detail that should be left out of the requirements document is development instruction. The end users and business analysts are aware of the organizations’ challenges and the requirements to solve these problems while the development team is better positioned to develop the software that meets these needs.
Adding scope without adding value.
- When reviewing the requirements with the development team there is occasionally the notion of taking the car mechanic “while we have the hood open” approach. Here the developer feels while we’re already in there and touching one piece of code, we might as well throw ‘x’ in. While ‘x’ might only be a couple lines of code or a day’s worth of work, it can add a level of complexity to testing and since it was introduced at the last minute the ramifications and downstream effects were not fully vetted, which can in turn cause more problems down the road. A business analyst should always consider developers ideas on ways to improve upon the requirement or an alternate approach, but there must be a clear value add associated with the change to accommodate the additional scope or increased timeline.
