5 Keys to Great Requirements Documents

12 09 2008

Critical activities in any software project heavily rely on the presence of high-quality up-to-date business requirements.

Architects base the architecture and design of a system on requirements. QA draw their test plans from requirements. Developers start working off documented requirements… that how it should be at least.

So bottom line, you will have to record requirements in one form or another. This applies even if you’re an agile process supporter who believes in light documentation. The following tips can and should be adapted to suite your documentation practices.

Prototype First

Frankly, I don’t know how anyone could NOT do this step. Prototyping really simplifies requirements documentation. The prototype usually becomes the most important part of requirements, for the following reasons:

  • It minimizes the inevitable risks of requirements change, and gives your requirements much wanted stability. Users start to be enlightened and understand what they really want as soon as they have some working prototype to interact and play with.
  • Screenshots (an output of basically any prototype) are essential parts of Use Cases or User Stories; they reduce the amount of writing required to the minimum… you just include the screenshots and reference them.

Prototypes can be as simple as drawings and sketches on white paper, more complex and interactive like “paper prototypes” or can be done using a specialized prototyping tool.

But the prototype is only the beginning of the story. While prototyping, you should start planning how you will document the requirements represented by the prototype.

The next step is to…

Know and Honor Your Audience

In all documentation I’ve seen and examined, this is one of the most ignored fundamental principles. You have to understand who you are writing for, and then write to give them what they expect.

First and foremost, you write for your customer. So pay them due respect and:

  • Understand your customer’s lingo and use it.
  • Write in the customer’s preferred language, if possible.
  • Organize requirements in the document by priority – the most important to customer first.
  • Use simple diagrams and illustrations extensively – customers really dig pictures way over long boring text.

Don’t forget the rest of your audience in the project team. Understand what they expect and take their input into consideration.

Never Start with a Blank Page

Templates exist out there for a reason. One of the greatest opportunities in documentation writing is to re-use the knowledge and experience gleaned by other people in the form of templates.

Starting with a template can give you a great jump start. But almost always, any template needs customization to fit your needs. Strip a couple of sections, add a few, and change the name of some others until you are satisfied.

The point of customization is to create a simple and concise document. You have to question the presence of each and every section in your document. Ask yourself questions such as: is that section really relevant? Who of my audience will find it interesting and why?

Great templates that I’ve used myself include those of the Rational Unified Process (RUP).. you can also take a look at the templates of the open-source ReadySET project.

Pick a Style and Be Consistent

“Consistent” here must be in everything – from your writing style of Use Cases and your use of terminology to the use of diagrams. Consistency makes it easy for anyone to quickly scan the documentation for a piece of information… not to mention being a fundamental trait of any professional document.

Be Prepared For Change

You must have heard it thousands of times: the most certain thing about requirements is that they do change. If you do not keep up with the changes, the requirements document loses its value and fails its purpose.

That’s why you have to be careful while picking your prototyping technique. Is it easy to update your prototype?

But what should you do when requirements change? Do you go back and change the requirements document? Yes and no.

Yes, if the requirement item (use case or feature description) has not yet been implemented. You go update your prototype and your requirements document.

The answer, however, is No when you have already implemented these requirements. At that point, the system itself manifests the requirements. So you go update the system. But that will leave the requirements document outdated, won’t it?

In my opinion, this is fine – as long as these changes are tracked in an issue tracking system. That way, you can spare your effort and “batch update” the requirements document if you ever needed or wanted to.

Review and Refine with Your Customer

After you’ve produced something, don’t just email it to your customer and expect them to review it or even read it carefully. That ain’t happening. Except in the most motivated of customers, the correct way to do it is to go in person and review and refine it with them.

Oh, and on the way, arm yourself with the patience of an ant — you’ll need it.




2 responses

15 09 2008

Some great tips, a little bit ‘common sense’ for some of them, but I’m sure that there are people sitting in front of the keyboard with an empty document just looking for a bit of guidance that this will really help.

25 05 2009
Mark Shehata

Hi Moataz , Interesting post … I have just finished a 2 semester graduate course with Prof. Barry Boehm, this course focuses on Software Engineering using Incremental Commitment Model (ICM) one of the good practices we learned regarding the requirements preparing a document called Operational Concept Description this one includes the BIG picture of the desired systems (Business Goals, Current System, Operational Capailities, Level of services, current business workflow, …etc) all the previous without any details once you have this big picture ,You can start a draft detailed Requirements Document then after some reviews you MAY have the finalized one cause as you mentioned the Requirements could change …

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: