This article is initially available on our podcast. Click here to listen.

Generating a requirements document can be challenging. These go by various names: Software requirements or requirements specification. Back in the day, end-users called them functional requirements.

The objective when you’re building something, it’s akin to having a plan for your house. You don’t want just to lay a foundation and throw up walls if you haven’t decided on exactly what you’re going to do because the roof won’t line up, and the walls won’t connect. It’ll be a complete disaster. In the worst case, somebody will try to add something on, and it really won’t work. It’s basically like having an architect and engineers come up with plans so that you know exactly what you’re going to build. That’s why you need a requirements document.

It can be quite hard, especially since rarely do clients of ours have excellent documentation that shows what they’re researching. Sometimes, building software can be automating something you can already do manually. For instance,  someone is doing something in Excel or pushing some documents or something else. Sometimes, it’s doing something completely new. This is a wish list. This is something that they would like to do, but they’re not already doing. 

Your existing processes need work

Often, there are many benefits to doing something new. Invariably, that’s the case. It’s just that those are very different processes when one doesn’t exist and one already exists, even if it’s manual or offline or a lot of Mechanical Turk.

An existing process is often easier to automate because someone has already worked through many operational challenges and much of the details for what it is that they need, even if it’s something as simple as Excel. They’ve done a few things, or they’ve put in some if-then statements, or whatever it might be to try to figure something out. They’ve attempted to join some tables with VLOOKUPs. 

Since we deal with data and a lot of data wrangling and automation, frequently, those are the types of things there are. At least, somebody has done something that validates that that is what they need.

There are many problems with that. We’ve seen many situations where if multiple managers are trying to do the same function, the processes may not be consistent. One’s doing one thing, while another one is doing something completely different. It’s often not clear what they’re doing or what they’re trying to accomplish. In fact, we’ve seen managers who don’t even understand what it is that they’re doing or trying to do. So we see extreme variation between different people trying to perform the same function.

Typically, if something’s been happening for an extended period, several years, five years, or you’ve had some turnover in a position where somebody did something and then trained somebody else to do it, it morphs dramatically away from its original requirements, original goals. There may be conflicting wants or needs, or somebody injects their own bias into what they’re trying to build. So it gets kind of complex.

Build the fundamentals first

Often, we see when people are trying to have us develop applications for them in using data, data in analytics, there’s frequently a mix of automating something that’s existing and a liberal wish list. Somebody says, “Ah, we’re going to automate what we’re doing now, but let’s add in all these things that we want to be doing.”

An even more nuanced problem that we run into frequently is people say that they’re already doing something when they’re not. Some manager says, “Okay, this is what we’re doing.” We try to document all of it, and it turns out that half of that is a wish list. Now, some of that is because they’re just trying to stuff in as much as they can. They want to say, “Hey, if we’re getting somebody to build something for us, let’s build a Cadillac, or a Ferrari, whatever it is. Let’s get as much functionality as we can.”

Part of that happens. More often than not, though, I think we find that the executive, the top-level manager, or something like that made some requirements that somebody would do something. They say, “Hey, you have to perform these functions and these analyses or get this data or answer these questions.” 

And there’s a belief that that’s getting done. We find out that that isn’t the case. Somebody is half-assing it a little bit. I’m not casting any judgment. It’s far more complex than they’re able to handle, and, therefore, they do what they can. That turns out to be half of what they expect or believe they can accomplish.

Document your processes

We’re not Big Brother. We’re not trying to show that not everyone is doing what they’re supposed to be doing. However, it’s ubiquitous for us to come in and find out that only half of what they think is getting done is getting done. It’s so complex that they haven’t wrangled it all because it’s almost impossible to do all of it in Excel.

We know that we’re in deep trouble when we’re developing a requirements document. We go through all of it. We write it all up. It’s 3-to-15 pages, depending upon the scope of the project. We have the client sign off on these requirements that are saying, “This is exactly what it is that we’re going to build.” Then, as we start building the application, we get halfway into it, and we realize, “Ah, there’s something that we didn’t see, we didn’t anticipate.” 

Even though we’ve done so much work ahead of time, when we’re trying to build it, we find, “Hey, here’s a case that isn’t accounted for. What do we do in this situation?” or “How do we handle this if this breaks this?” We come back to the client and say, “Hey, here’s the problem. Maybe, even here’s the suggested solution. Do you agree? Can we sign off on a change to the functional requirements or the requirements document?” And they sign off on it without any discussion or any significant changes.

That tells us that we’ve got an issue because they didn’t see the problem before. They didn’t realize that was the case. They agree to a new specification without even realizing, “Hey, there’s probably more,” and they need to go in and make sure that they understand their processes or what they’re trying to accomplish. That means they’re just winging it.

We always ask people to walk us through exactly what the current processes are, what they want us to do, where the data resides, walk us through the systems, how we pull data, where it is, how we find those fields, the particular documents, the particular files, the structures, the metadata,and anything else associated with this detailed process. 

We spend an enormous amount of time combing through and understanding that and documenting all of it. If they don’t even understand all of their processes, we’re in trouble.

The difference between automating a manual process and creating new things is enormous. We frequently run into hilarious situations where we’re asking somebody to walk us through the existing process, and they say, “And we do this and stuff” or “We do this and other stuff like that” or “Any other things.” Whoa, whoa, whoa! Stop right there. That was a very vague statement. What stuff? What things? What fields? What records? What payers? You have to define these very carefully. If they don’t have an existing list, that means that they don’t have their process down, even if it is manual. Unfortunately, this is common and typical.

One suggestion we have is before building any software or having somebody make it for you, execute it manually and document everything you’re doing. Even if you’re doing much manual work, many workarounds, a lot of Excel, things like that, have somebody do a mock-up, a prototype, something to do exactly what it is that you want to do because you will find all kinds of problems that you didn’t anticipate, explicitly concerning critical components, including:

  • Business rules
  • Requirements 
  • How things function 
  • Use cases


Spending more time on defining and mapping out your processes and requirements saves a lot of work and many headaches down the road. That’s the best advice we can give you.