A proper requirements document is critical to a successful software development project. Any resource on software development worth a dime will tell you that. At Vision Point Systems, we’re open-minded and we realize that different people have different ways of getting things done. What works for one may not work for all, and one organization’s practices may not be a good fit for another organization. That said, EVERYONE must accept that a proper requirements document is critical to a successful software development project. It’s an article of faith for us, and a primary element of our own policy, but a very cursory web search will find people who agree with us. The Requirements document is the rock on which your project is built, and if it’s not solid, everything that follows is suspect. Rather than titillate with stories of bad requirements-we’ll do that in later posts-we thought we’d focus on what they should be.

The Requirements Doc fully defines a product or the new feature(s) of the product. The Requirements Doc is the ultimate reference, the final arbiter, and the foundation for all other documents used in the project.

The Requirements Doc allows people to understand what the product is, what it should do, and how it should work. The Requirements Doc is the official, written understanding between the client and the company of what is being built. The Requirements Doc is used to bridge the communication gap between two species: the client and the developers. The goal of the Requirements Doc is to fully explain exactly what the client wants in such a way that a developer can build the product.

The Requirements Doc is not, however, a System Design Specification. That is, the Requirements Doc lists the system’s functional requirements – how it behaves, what it looks like, what goals it should accomplish – but does not specify exactly how this will be done.  The Requirements doc also includes the non-functional requirements, how quickly it will complete a task, for example. The Requirements Doc can list the constraints or business requirements from the client’s side (for example, the product must work on a specific operating system); it does not, however, attempt to dictate the design solution.

Because the document is used to translate a customer’s high-level conceptualization into a developer’s low-level detailed code, the language of the Requirements Doc must be closer to natural language but also unambiguous and clear. There should be no requirement that the developer has to interpret.

The Requirements Doc also serves as a validation document, used by testers on both sides to determine if the final product works as expected. Therefore, each requirement statement should be testable. (More on testable requirements in future posts!)

The Requirements Doc should be as complete as possible before development begins. A Requirements Doc, with stakeholder signoff and clear, testable requirements allows developers to proceed without worrying about wasting effort following essential requirements that are later changed. (In addition, the requirements themselves should be high-level enough that a change does not adversely affect the design solution.) Of course, the client may request further enhancements later; these would be added in a later release.

There is nothing radical about this idea, but neither is there anything particularly easy about it. Consider this a public service announcement from VPS: Do the hard work of writing your requirements document, and there will be far less hard work building your application without it.