Business Analyst/Product Owner: How to write accurate software requirements

This blog post was originally posted here on the alvinalexander.com website.

When you’re working as a business analyst, the words you write are what you get paid for. Just like the author of a book, when you write software requirements, you shouldn’t be loose with the words you write.

While working on a recent project, I started thinking about software requirements again, and was reminded how vague a requirement can be, even when you think it’s well written. What made me think about this today was running across this performance requirement I found in an a requirements specification:

“The system shall load a web page in no more than seven seconds.”

As software requirements go, that doesn’t seem too bad. I’ve seen much worse, but...

Making software requirements more detailed

When I look at a software requirement like this these days, my mind instantly starts asking questions, questions of the “Who? What? When? Where?” variety.

Here are the questions that come to mind when I read this software requirement, and the changes I make to the requirement based on my answers to each question.

1) Which web pages? I'll assume this should mean all web pages rendered by our application, so I rewrite the requirement like this:

The system shall load all application pages in no more than seven seconds.

2) How many users? What server load? An unused application will run much faster than a swamped website. We can either improve this requirement, which I'll do here today, or even better, we can write additional performance requirements for our system.

The system shall load all application pages in no more than seven seconds with 1,000 simultaneous user logins.

You’d be amazed, but adding a few simple words like those that are more detailed can stimulate a lot of additional conversation among your requirements reviewers (“What do you mean, ‘1,000 simultaneous user logins?’”), and I think that's a very good thing.

3) What network? You can't just say 'network' or even worse, 'internet', because in the first case this isn't clear, and in the second case you have no control over the Internet.

The system shall load all application pages in no more than seven seconds, with 1,000 simultaneous user logins, as demonstrated on our 10Gb test LAN.

4) What type of computer? Again, this may seem like a minor point, but you need to be clear here. A ten year old computer will load a web page much slower than the newest system at Best Buy, and a new iPad loads a web page much faster than a four year old iPhone. So one more change:

All application pages shall load in Firefox, Chrome, and IE browsers on our standard desktop PCs in no more than seven seconds, under maximum load conditions of 1,000 simultaneous user logins, as demonstrated on our 10Gb test LAN.

While that may strike you as too much corporate-speak, I think you'll agree it's a much more accurate statement.

As a final note, as I look at this, I would even rewrite "1,000 simultaneous user logins" as something like "1,000 simulated user logins", but language like this will vary depending on the people reviewing my requirements.

One more possibility that comes to mind here is breaking this up into multiple statements, but I'll leave that as an exercise for the reader. :)

Software requirements, user stories, and details

Some of this may seem over the top to you, and I need to add that how you write your requirements, use cases, or user stories certainly should vary by your audience. If I'm working with a small, agile team I might never write a requirement like that. You can write your software requirements much more loosely when everyone on the team knows each other very well, but when you're working with a much larger team where precise communication is essential, it helps to be very specific.

My point here is this: If you can learn to write very detailed, specific software requirements and use cases, you can easily tone down your language for less formal specifications like user stories. But the opposite is not true.

Reporting live from Longmont, Colorado,
Alvin Alexander