Software Requirements Specification Template

We’ve just updated our suggested business requirements document template, though it can be used as a template for any type of requirements specification. You can find it here on our Resources page. One thing we strongly suggest is that you create and update requirements within a requirements management tool and then output as needed to a document such as this. We use Borland Caliber and have found that it is relatively easy to export from Caliber into this format. This is a great way to deliver your requirements to the team, but if you can avoid it, do not use the Word document as your source as you will likely step on each other eventually and it makes traceability very hard!

Project Pulse - Constraint Tracker

I was just wrapping up a project co-writing a 90 page requirements document for a client and I am so proud of my work! Unfortunately our statement of work with the client says that we would only document at most 45 pages estimated at 3 pages per requirement. With this data in hand we were able to approach the client about this potential budget buster. We were both able to come away from the situation happy due to extended budgets and robust requirements. What if this happens to you? What if you aren’t working on a project that has the luxury of flexible resources? Are you prepared to protect it from hitting that brick wall?

You probably need some sort of daily gauge letting you know where your project is in relation to your constraints. Some common project constraints are pages of documentation, number of requirements, hours, or budget. Try to keep track of these stats daily to maintain a dashboard both for yourself and for the stakeholders on your project.

It could look something like this:

These graphs will provide you with a quick easy to understand overview of where you are with your project constraints. With this understanding, you can better direct your work or your teams and when needed, go to your stakeholders and tell them that they may not get what they wanted with evidence why. It could motivate them to provide you with the additional resources you need to get the project completed right!

Reqlish: Part I: English Usage and Syntax for Software Requirements

Justin Burrows says:
Hey James. I got a sooooooooooooper dorky idea: Let's do our blog post on Requirements English (I'm calling it Reqlish) over Skype.

*Justin Burrows is pleased with himself *

James Hulgan says:
LOL. Alright, ready set go.

Justin Burrows says:
We're brought up to mind our p's and q's, but is good English really suited to Requirements? Especially when working with global teams, a simplified "pidgin" may actually work better for requirement documents. The pidgin that I use has this consistent structure similar to simple, formal language:

[Subject] [Verb] [Object] [Exception/Modifier].

But I also drop articles (e.g. a, the, an) and instead use all caps to indicate specific systems.

James Hulgan says:
Yes, "proper" grammar does not always buy us what we want as requirements analysts--that the requirements are easily consumable and understood. Often, the way in which requirements statements are structured grammatically is ignored, but it is crucial to how well the requirements are understood. Some grammatical purists may disagree and claim that we should always use proper rules of grammar in our writing. I would respond by staking out two possible positions with respect to grammar:

1. The Orthodox: Think your junior high or Freshman English comp teacher. Motto: “There is a Correct and Proper English Grammar, and anyone who deviates from that grammar deserves to be publicly humiliated.”


2. The Pragmatist: Not sure there is an archetypal linguistic pragmatist, but I think of my sophomore English teacher who encouraged my fiction-writing. Motto: “Grammar is a tool: Use it and modify however you can in order to get your point across the best way possible”.

As a requirements analyst, we have to be pragmatists.

Justin Burrows says:
I find this "Reqlish" is often a battle between logic and ear. For example, saying "a equipment" instead of "a piece of equipment" sounds awful to me, but perfectly normal to consumers to whom English is a second language.

But, James, I put it to you:

Are these grammar shortcuts that this crap up anymore with which the latent grammar nazis on the team will not put?

James Hulgan says:
I don't think that we should care so much about the grammar nazis. We should spend the effort to ensure our requirements are grammatical only if it serves the purpose of ensuring that the requirements are unambiguous. If making the requirements "ungrammatical" furthers the cause of consumability and understandability, then it is worthwhile to discover the structures which make this possible. Not too many people these days, besides crotchety junior high English teachers, believe in "one true grammar" for English anyway.

Justin Burrows says:
I think there are a lot of closeted Junior High English Teachers out there (and you know who you are-- Alright is a word, btw. :P). Do you think there are "rules" that Reqlish would play by?

James Hulgan says:
Well, it probably depends on the project, but I think something like [Subject] [Verb] [Object] [Exception/Modifier] is a good start. Trying to avoid ambiguity is an awesome goal, but to very loosely paraphrase John Searle, “Syntax does not suffice for semantics”. In other words, one particular grammatical structure is not guaranteed to be less ambiguous than another.

*Justin Burrows rings the idiot bell.*

Justin Burrows says:
Ok, smart guy, want to explain the distinction between Syntax and Semantics?

James Hulgan says:
Briefly, a language's syntax is the rules for how items (words) in a sentence of a language can be arranged. Semantics is the meaning of the strings in a particular language. So, while the meanings of sentences certainly depend on syntax, a particular syntax is not sufficient for conveying meaning.

Justin Burrows says:
Huh…

James Hulgan says:
There, like, has to be a balance, man.

Justin Burrows says:
Ok, I can dig it. Can we talk more later about building a formal syntax for Reqlish?

James Hulgan says:
Sure! I chatting syntax. Let's go more into the subject-verb-object structure and what structures are most easily understood. And next time let's give people some practical examples to use in their own documentation.

Your Requirements Best Practices Are Not Your Reality

To begin with an analogy: I have a friend that can be unreliable sometimes and show up late when we have plans to meet. This is especially difficult to manage when we are meeting to see a movie – if she shows up 30 minutes late, then the movie date is off because the show has already started by the time she gets there. She’s a great person to be around, just difficult to manage at times. We agree that we need to meet 15-30 minutes before the show time (best practices), yet something happens and she shows up after the movie starts.

If our plan to see a movie was instead a project for which I was the requirements expert and she was the project lead, then the concept of showing up 15-30 minutes before show time would be a recognized best practice. So what to do when an acknowledged best practice conflicts with what the project lead wants (the right to show up late in the case of the movie example)? The lead wants the benefit of the best practice (seeing the movie), but things happen or constraints are in place that create a situation where this cannot be done.

What I should do (Best Practices) ≠ What I’m going to do (Reality)

The first step I take in these situations is to first fully understand the project lead’s reasons for not being able to apply the best practice. From the movie example: perhaps my friend is taking college classes at night, and they end right before the movie meeting time. In that case, we could just meet for a later movie, or wait until the weekend. Can the lead and I find a “movie time” that works for everyone where we can still apply the best practices?

In the very rare case that the project lead is simply in disagreement with the use of the best practices, then I determine if it is something worth arguing for. How will the project be affected if we do not apply the best practices in question? If the impact is minimal or can be easily negated and/or managed, then it makes sense to apply the practice that the project lead is requesting. If the impact is too great to ignore, then I work to convince the lead to trust me and let me demonstrate the benefits of applying the best practice.

By the end of the project, we are laughing and munching on the last of the popcorn together as we exit the theater.

Why Should You Use Requirements Models?

Why should you use requirement models? Isn't it faster to just start listing the functional requirements? In this post I'll explain why you shouldn't do that - and why requirement models are so powerful.

Provide Context
You cannot pick up a list of 500 system shall statements and quickly get a grasp of what the system needs to do. Higher level models, such as System Context Diagrams, Entity Relationship Diagrams, Process Flows, and Organizational Charts are great ways to understand the complete picture. Other models can provide important contextual reference for developers, testers, and others that need to consume the requirements (Use Cases are great for doing this).

Help Derive Requirements
Models can help you generate requirements quicker than you could than without them. Use Cases are a great example of this - once you've generated the series of interactions, it is relatively easy to examine each step and ask the question "what does the system need to do to support this step?" Likewise, you can examine interfaces within a System Context Diagram and start thinking about what requirements are necessary to support them.

Prevent Missing Requirements
Going back to the proverbial list of 500 system shall statements - it is nearly impossible to look at a list like that and determine if anything is missing. There's a post here that describes this in more detail.

Easy to Utilize
Most models are easy to read and use. If you've ever had difficulty getting stakeholders or end users to review your 200-page document (and who doesn't love to read those!?), consider leveraging models to shorten the review time. It's a lot easier for someone to validate requirements while using a Process Flow or Use Case than it is without them.

So avoid the temptation to jump straight into the requirements - your requirements will be more complete, have more context, and will make it easier for others to validate and use your requirements.