Requirements, Worth the Read


Over the years, I’ve read, written, reviewed, and otherwise made use of a large variety of Requirements documents. Many were exercises in typing, some were a bare minimum to meet a checkbox, and others were useful tools. The latter ones are invaluable, and the others should be so, but aren’t due to process-heavy development cycles or teams just trying to “deliver the mail”.

Regardless of the type of Requirements document provided, it is important to not only understand the requirements, but to know how they might impact each other.  Some of this requires experience, the rest just requires a little time.

I present three, out of many, situations that could have been avoided if a little attention had been applied to understanding the requirements.

Curse of the Old Requirement

A product had been developed and deployed for years. When a new PM came on-board, he reviewed the requirements for the upcoming release. He saw a requirement that was not covered in the Test Plan. It was an original 1.0 requirement that hadn’t gotten any attention in quite some time. A little research showed that it was not only not currently being met, but most likely had never been implemented.

As a developer, you are not only responsible for the current requirements, but all of the requirements for the component being delivered. It is not just enough to add functionality. It must be integrated and all other functionality needs to be validated.

The question was what to do about the requirement. Nobody had ever noticed before. Should it be added at the late point of the release cycle, where people would notice, or slipped into the next release? The decision was made to add the functionality, though it was never mentioned that it had ever been missing, just “enhanced”.

Lesson: Once you take ownership of a component, you “own” it. Know all the requirements, past and present.  There is no blaming the previous developer. If something was missed, feel free to grumble about the previous developer, and then fix it. If you don’t fix it, it is not fair to blame the old developer for the miss.

The Local Web Application

Here is the scenario…a client didn’t want to purchase an import tool due to historically long and painful procurement processes. There wasn’t a lot of content to import, so it was decided to create an throw-away import tool. Here were some requirements for the tool, and the system:

  • Network administrators were not going to be allowed to run the tool. There were a lot of privacy concerns regarding some of the content and the people importing the content must, by the nature of the tool, have access to it.  This meant that selected end-users must use the tool in an environment that they could authenticate against, like their desktop.
  • Firewall rules prevented access from the desktop to the back-end servers. It was port 80 to the web servers or nothing.
  • Only data center administrators were permitted to log into the servers. This meant no logging into the system just to run an import tool.

The decision was to create a web-based tool. It could run on the web server while being controlled by the user through their browser with full access to their network share.  I wasn’t a big fan as web-based imports tools can be slow. With the constraints, including budget, what can you do? Just build it.

Tool gets built and tested. It failed in the Test environment.  Why?  Simple, the developer always ran it local to the web server. When it was run from another computer’s browser, it failed. The argument was made that the tool technically works and could be fixed later. My thought was, No, it doesn’t work at ALL. A web application that can’t run on a browser not on the web server isn’t a real web application.

Lesson: Read all the requirements, not the one that says “Create something that does X”. No requirement lives in a vacuum, they all influence each other in the design. Understand the why of a requirement and how others relate to it. Test accordingly.

When You Said All Components, You Weren’t Serious, Were You

A product comes with an API. It is extensive and tested as thread-safe. It works well, or at least well-enough. Another product team creates a new optional component for the product. After a few release iterations, it is well integrated with the main product. A decision is made to produce an API subset that developers can use for this optional component.

Sounds great. Does that thread-safe requirement apply? Customers would have said yes, but the customers weren’t consulted. Bug reports were opened and a fix was issued in a subsequent release.

Lesson: When writing new components for a system, look at the overall system requirements. You inherit those requirements. Act accordingly.

The Chaser

There are lots of requirement lessons out there. The key is to understand and document them. If you have to add lots of process documentation around them, make sure to have a sound Requirements Traceability Matrix (RTM) handy.  That will allow people to readily digest the requirements and find out where to find additional details.

Of course, if you have a process heavy, highly-verbose Requirements document, odds are you have an RTM, whether you want one or not.