Mike’s Dump

March 21, 2007


Filed under: Work — mikesdump @ 1:32 pm

The past couple of days I have been in a few conversations around requirement documents. After giving it some thought it was time to do a brain dump.

What Do You Want?
I think what gets lost when more technical people write requirements documentation is what is required. Instead of focusing on the project from a user point of view they are thinking how they would implement the feature and write instructions instead of requirements

Create a table called customer to store customer information. The following fields should be stored . Write an after update trigger to capture any modifications in the customer_history table.

Is the above requirement wrong? No. But, does it really matter from a user point of view what the table is called? Does it have to be a database trigger for history tracking? Instead something simpler could have been written in the requirements document:

All fields on the customer screen (see screen shot) need to be saved. Anytime changes to the customer information are made a copy of the original information should be made so the changes over time can be viewed on the customer history screen (see screen shot).

You don’t have to be technical to communicate what you want an application to do the key is knowing what you want.

Screen Shots
A picture says a thousand words right? Seeing a drop down list beside a field called “salutation” right away would tell the developer that list of salutations is going to have to come from somewhere. This should bring up questions like:

  1. Does this list need to be modified by the user?
  2. Modified by administration staff?
  3. Or never modified?

Seeing this could mean creating supporting screens, tables, or simply hard-coding the values. Only seeing in writing the requirement for a field called salutation could be easily overlooked and created as a text box instead of a drop down.

Test Scenarios
Adding what scenarios are going to be tested to the requirements document will sometimes highlight areas where the requirements may not be clear but also gives the developer the ability to “test like a user” (well, in theory anyways).

Undocumented “Features”/Implied Requirements
No matter how complete the requirements document is there is always potential for miscommunication. I believe there are several features in an application that are just assumed. For example, when a feature is to “save the customer” it is unlikely that would be interrupted as saving that information only as long as the application is open (persisted in memory versus persisted to a file or a database). It would be assumed this information should be available the next time the application is loaded as well.

Other areas that I have seen implied requirements are:

  • Validation � It may not be in the requirements document but if a user types a letter into a number field it shouldn’t crash the application
  • Security � In a multi-user environment users shouldn’t be able to delete data that doesn’t belong to them (assuming user data is private in this scenario)
  • Application Interface Consistency � This often gets overlooked in larger applications until several screens look different because each developer implemented it in their own way.

These particular examples could be covered off by standards documents so requirement documents don’t become bloated.

It Isn’t Written in Stone
The worst thing that could happen from a good requirements document is it is used as a replacement for conversation. A good requirements document is only the starting point for creating working software which is what both developers and users prefer.


Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

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

Blog at WordPress.com.

%d bloggers like this: