Requirements: You’re Probably Doing It Wrong

A Senior Business Analyst once said to me that requirements are finished when the developer has enough information to build the application and the testers have enough to test the application.  Recently I have been thinking about what really constitutes good requirements.  Over the past 20 years, I have been in various situations with wildly differing levels of requirements.  I can think of one situation in particular where the manager at a major financial institution sat me down for two hours and verbally told me everything she wanted in the application.  While I wrote down as much as I could, some requirements were missed that were implied in her mind.  Engineers have yet to create a mind reader.  Giving verbal requirements is setting the project up for failure.

On another assignment, the manager sent all the requirements through Instant Messenger.  One thing about text requirements is that is nearly impossible to guess at what the application should look like.  Conversely, I had a co-worker at the same assignment where the manager created a mockup of the application on a scrap of paper.  The co-worker saved a scrap of paper and told me that that it was the best requirements that he had ever received from that manager.  I had also received wireframes on the same assignment and it was up to the developers to guess what the functionality was supposed to be.  Guessing at requirements is setting the project up for failure.

On my current assignment, they are stuck in Waterfall for their requirements process.  The business has created a 700-page requirements document that has no wireframes and describes in detail how the current system performs instead of what the new system should do.  Large documents by their nature look impressive and detailed but they have the opposite effect of creating so much noise that the requested functionality cannot be seen.  This is typical for government institutions and other enterprises with software that has a high business risk (financial institutions and insurance).  Requirements should not be a novel but a short story for each screen.  In some cases, there is so much irrelevant information that the developers have no chance of correctly implementing the system.  In addition, the testers have no chance of correctly identifying what is important enough to be tested.

I worked with a Business Analyst that had once worked for the government where she was used to creating large weighty documents.  It was a difficult transition for her to go to Agile.  While she created wireframes and organized the business rules into sections; she repeated business rules and added information that was not relevant to the project.  We had several clarification meetings to talk about the repeated business rules that were worded in slightly different ways and the impact of the non-relevant information (in other words it could be ignored).  While Grade B requirements can be used to build an application, time is wasted in clarification meetings.

So what are Grade A requirements?  This is what I use when leading a team:

• Overall, the requirements should be written in such a way that it can be understood by the business, that there is enough clear information that the developer can implement and there is enough clear information that a tester can write test scripts.
• Requirements should be signed off by the Business, Developer, and Tester. Any one of these parties can reject the requirement if the requirement cannot be used to actually build the application.
• The requirement should be broken down by the screen, or if a process is very complex it may warrant a separate requirement. Example:  Saving a Customer will synchronize with a third party Customer Relationship Management system.
• Include a revision history in the document. Any changes to the requirements are given to a developer should be in a different color per revision.
• A global requirements section should be at the top for items that always apply. Example:  The application will run under Internet Explorer 10+, Firefox, and Chrome
• The requirements should have a wireframe for an internally facing business applications. If it is an externally facing application a designer should create an exact mockup with applicable designs for desktop, tablet, and mobile views.  The HTML colors should be clearly listed.  The developer or tester should not have to guess how the application should look.
• The fields and their validation rules should be listed below the mockups.
• The buttons or hyperlinks should be listed below the fields with their functionality explicitly defined.
• Any other business rules should be listed
• Business rules should be listed once
• Irrelevant information should not be included. Examples of this include; existing functionality that does not need to be changed, history of the project, a list of developers that no longer work for the company.

How do your requirements measure up?  Grade your enterprise.

Grade F – Verbal Requirements.

Grade D – Informal Requirements: instant messenger, email, or stand-alone wireframes.

Grade C – One giant, useless, incomprehensible requirements document.

Grade B – Requirements per screen with some duplication and irrelevant information.

Grade A – Requirements per screen with wireframes, with no duplication, only relevant information.