As I’ve talked about before (and everyone already kind of knows), good requirements are a key driver to success. To put it simply, you need to know what problem you are trying to solve for your customer, what your end user really wants, and what they are expecting you to build. It’s all about Expectation Management. And the preferred and accepted way to codify all this is by authoring and documenting requirements.

But what does that really mean? What are requirements? And how do you document them?

The traditional method is the classical, “INCOSE style” of requirements, which is also known as the Software Requirements Specification (SRS) or Statement of Work (SOW) method. This method is typically just a list of written statements or sentences, usually written as what are known in the biz as “shall statements”.

The software application shall run on iOS version 11 or later

The software application shall allow the user to enter the date that the shipment is due

There is a huge body of knowledge on how to write requirements like this. Many authors have attempted to provide the guidance on how to author such a document in a way that is successful.

• Complete
• Consistent
• Feasible
• Modifiable
• Unambiguous
• Testable

To be honest, I don’t care for this method for a myriad of reasons. It can be difficult to organize. When the projects get to any significant size then you end up with hundreds, if not thousands, of these shall statements. How do you organize these? Quick, tell me the difference in a functional requirement, technical requirement, capability, constraint, and assumption. Finding the specific section you are looking for becomes a huge challenge.

Furthermore, how can you reasonably organize and understand all of them? When you have so many requirements frequently they will contradict one another in non-obvious ways. Or you’ll be working to design and implement one known set without the contextual knowledge that there is another set of shall statements somewhere that you need to comply with that you don’t know about.

Many large, formal projects and contracts work this way, and to be blunt I believe that is why so many of them fail. Handing 450 shall statements to a software development team doesn’t really tell them what you really want, and no matter how hard they work it will be near-impossible for them to meet all the requirements (since some will contract each other, or some will be unfeasible, or some will just be plain wrong for what the customer really wants). And then the product is considered to not meet the requirements and is considered a huge failure. Or worse, the product meets the requirements perfectly but the requirements are not well written so the end-user hates the product and it’s considered a huge failure.

Any of this sound familiar?

I know there are people out there that say “if only the requirements had been written correctly then everything would have been fine”. There’s still a couple things wrong with this.

First, from a pragmatic perspective that just won’t happen. The requirements will not be written well no matter how hard you try. It’s just like accepting the fact that your software will have bugs, or the users will hate the first release, so you need to just plan to it. (I realize there are exceptions to this rule, albeit very expensive. If you’ve got the money to do it that way, then sure do it that way.)

Secondly, in order to get the requirements written to an acceptable level, you have to know, at the very beginning, EXACTLY what the user wants. Anyone with development experience can tell you that no one ever knows EXACTLY what they want up front. You have to accept that things will change and be ready to adapt to it.

Luckily, there exist more palatable and successful ways of communicating requirements from the customer and end-user to the development team.

So first of all, what is REALLY the goal here? The goal is to deliver a product to the customer that solves their problems and is what they want. And the way to do that is to be able to tell the development team:

• What are the problems that are trying to be solved?
• What is it the user wants? (or thinks they want)
• Any technology or architectural constraints or integration needs

Here are the ways I like to document these things, to meet the goals above but still provide a codified, in-writing record of what the team promised to build.

User stories, usually organized by the types of users

This can clearly describe, in the user’s own words, what the problem is that we are trying to solve. What is the task that they are doing now that we need to do for them? Or what is the task that will need to be done? And how is the user expecting that it will work?

“As a warehouse user, I want to be able to set the date when a shipment is due.”

“As a delivery driver, I want to be able to see the shipment due dates on my iPhone.”

Concept of Operations, CONOPS

These can actually be fun to write. Spend some time just talking to the customers or end users. Get to know their stories, what it is they do, and what they want to do. Then just, using vernacular language, talk about it.

“The shipment team receives orders from sales, including a bill of materials and a due date. The warehouse team needs to prepare the shipment and package it up for a delivery driver. The driver then picks up the shipment and delivers it, so the driver needs to know the due date the shipment needs to be delivered by.”

Work Breakdown Structure (WBS), continuously updated

Although not as fun to write, this is important for the project lead or project manager to maintain. From a customer Expectation Management perspective, you need to be clear what you are delivering.

• Software Products

  • Warehouse web-based application
  • Mobile application
    • iOS version
    • Android version

• Instruction Manual

• Training Videos

Architecture Drawings

These are less for the user and more for the team, to understand how the different components of the system they are building have to work with each other. Defining the interfaces, software contracts (i.e. APIs or interface method signatures), and external integrations lets the development team have a clear understanding of what they are building. This also can communicate to the team (and the customer) where the system will be installed and run from, where and how the users will interact with the system, and what the deployment and maintenance footprints will look like.

It’s important to recognize that your users’ expectations and requirements will constantly change. As the product begins to take shape their understanding of the problem domain will deepen and they’ll realize they need other features or integrations. Instead of having hundreds of shall statements to dig through and struggle to update and keep in sync, you can instead just update a smaller set of documents that paint a more accurate and understandable picture of the end goal.