Where are the Project Requirements? Transforming Models to Text-EN

Some time ago, a student asked me a question that really caught me by surprise. It was at the end of a Requirements Analysis Techniques class. In it, we look at a number of widely-used analysis techniques, and the walls of the classroom were literally covered with models, diagrams, and templates.

I was at the front of the room packing up my gear when a student stopped by and said, “This is all such great stuff. I really learned how to ask a lot of good questions, do some serious analysis, and I feel like I’m way less likely to miss something on my project. But…where are the requirements? I still need to know how to write the requirements.”

(Insert a brief but awkward silence here.)

My response? “The requirements are right there – in the models. You’ve captured them as you’ve been doing your analysis.”

To which he replied, “But I can’t just give my developers a bunch of models. They want actual requirements.”

I thought about this for a minute, and I had a sneaking suspicion that I knew the source of our disconnect. I asked him to tell me what he thought a requirement should look like. Turns out that in his organization, requirements were only requirements if they were captured as text statements. Ah…my friend the “System Shall…” statement.

He’s not alone. I have a lot of students and clients that still rely on textual requirements. So does that make models and graphics and templates useless? No way!

Different Task, Different Tool

If I needed to tighten up a doorknob in my house, I’d probably get out a screwdriver. It’s the right tool for that job. On the other hand, if I needed to pound a nail into the wall to hang a picture, I probably wouldn’t use the screwdriver. I could….it would sorta work if I pounded on the nail with the handle of the screwdriver…but it’s not the best tool for the job.

The same thing is true with project requirements-related tasks. There is a difference between analyzing requirements and representing them. So, with props to Dictionary.com, let’s agree on what analysis means, and what representation means.

• Analysis: a method of studying the nature of something or of determining its essential features and their relations
• Representation: the act of portrayal, picturing, or other rendering in visible form

I often find visual techniques and models more useful for analyzing requirements. It’s easier for me to spot gaps and inconsistencies in visual representations than it is for me to find them in text. Let me give you an example. I borrowed this text from IRS Publication 521 (which has to do with deducting moving expenses):

Now just for fun, I converted that to a decision table…and I deliberately made a mistake. Can you find it? Phew!

I bet lots of you were quickly able to see that in the first column, I didn’t cover the case where the new distance is exactly equal to the old distance. It’s hard to find mistakes like that in text…but I think they jump right out at you in many visual modeling approaches.

So when analyzing project requirements, we should choose the tool that is best suited to the job, and that will help us be as thorough as possible.

Translation is OK

Once you have thoroughly analyzed a requirement, you should have captured it in some form or another. Now you have a choice. You can:

1. Leave it alone or
2. Transform it into another representation

Why would you transform it? For one of a million reasons. Like, your audience doesn’t want to learn to read an ERD. Or you need a different level of detail. Or you have to load it into requirements management software and the analysis technique you chose isn’t compatible with the software. Or your organization requires a certain format.  Or…or…or…

Let’s say that you have developed a decomposition diagram. For the sake of an illustration, let me use a tiny one as an example. (Disclaimer: This is not intended to be a complete…or even necessarily correct!)

Let’s also say you’ve also used our Capability & Process Text Template to dig into the details of those processes, and that this is one of your outputs:

Now, using Option A (Leave It Alone), your process requirements could be as simple as this:

“The system shall perform the processes as outlined in Figure A, Functional Decomposition Diagram and detailed in Figures B through E, Capability and Process Text Templates.”

If, however, you have to go with Option B (Transform It), you can simply walk through the structure of the models and translate them into text statements. Using the example above, I’m going to use the structure of the decomposition diagram to form my outline, and then I can extend it with the details from the Capability & Process Text Template:

This is just one example. If you look at most models, there is a fairly straightforward way to take the results and translate them into text.

Download our Requirements Package Template for this Capability & Process Text Template and more!

Changing Your Mindset

But wait, you may be thinking…isn’t that double the work? If I have to represent my project requirements in a particular format, shouldn’t I just start there and use that format for my analysis work too? I mean, I only have a limited amount of time to do my work, so maybe I should just go straight to my text requirements…

Well, you could. But going back to our conversation about using the right tool for the task, I don’t find text to be a great tool for analyzing requirements. It’s like using the screwdriver to drive in the nail. You can do it…and you’ll eventually get there…but it’s not the most effective or efficient way to do it. I think you’ll find that the time savings you get using an appropriate analysis technique will more than make up for the time you spend transforming your results into another format.

Interestingly enough, there are some visual models that most people will accept as “requirements”. Specifically, I find that most people will accept flowcharts as a method of representing requirements, and they will also accept prototypes. So if you work in an environment that still requires “system shall” statements, I’d encourage you to see if you can gradually introduce some of the other graphical models, and reduce the level of detail in your text statements.

Can you find the project requirements now?

I hope so! It’s like Prego….they’re in there! You just have to know where to look.

– Kathy