Software Requirements Specifications: The Right Way
5. Keep Technology and Design Out
Why keep technology out of business requirements? It took me a while to agree and comply with this rule. As a technologist, I am tempted to solve the problem, come up with a solution, and design the system. It is important to understand that you, as an author of software requirements specifications, should only concern yourself with WHAT the system must do and not with HOW it will do it. In other words, you must leave implementation decisions to those who will create the technical design specifications. SRS is a document that should be technology free. "The system" (as you call it) happens to be a piece of software that runs on a computer. When composing the SRS, try thinking of "The system" as an entity that has nothing to do with software.
The same goes for designing screens while creating SRS. Even if you have a degree in GUI design and extensive knowledge of "client/system experience," you must refrain from mixing technology (how to do it) with requirements (what is needed).
The following words should not be used in the SRS: Click, dropdown, screen, and checkbox. Instead, use such terms as press, select, and prompt.
6. Make the SRS as Complete as Possible
Incomplete software requirements specifications leave room for ambiguity which leads to more questions later on. Incomplete means "missing information." Sooner or later, somebody must list all validation rules for the "Validate Bank Card" requirement. If SRS is unambiguous, there are fewer questions, fewer assumptions, and therefore less rework later on in the project's lifecycle. You can think of it this way:
An application developer is like a truck driver. The truck driver has to pick up and deliver freight based on a predefined schedule. If the truck driver does not know the schedule, he will set his own schedule and he will improvise.
Furthermore, a complete SRS allows application developers and the quality assurance team to provide more specific estimates. Can anybody give an accurate estimate on how long it will take to develop and unit-test the "Validate Bank Card" functionality? Unless it is decomposed into very specific requirements that can no longer be decomposed, the estimation would be inaccurate. However, once you know that "Validate Bank Card" consists of four specific unambiguous requirements, you can provide a more accurate estimate.
There is another important point: The quality assurance team can start creating test-cases as soon as SRS is complete. The benefit here is two-fold:
- The QA team can start creating test cases during requirements gathering instead of after application development is complete. This can be done because complete SRS tells you a full story.
- This is a very useful exercise because it validates whether the SRS is complete and unambiguous and if use-case realizations are correct and make sense.
7. Define the Level of Detail
You have already learned that the SRS must be complete and without any ambiguous terms. But what might look ambiguous to one community of readers might not be ambiguous at all to another community. Before you start composing the SRS, get an idea of who will develop your system. Will the development be done by an in-house IT or outsourced to a vendor? If it is done by an in-house IT, the staff is probably familiar with terms used in the SRS (proprietary systems, business terms, abbreviations). If the SRS is to be handed off to a vendor, the content should be as detailed as possible.
Also, keep in mind that your audience consists of stakeholders, developers, QA, and product managers. You must find the common language among all of these groups.
Let me give you a trivial example:
Company XYZ has implemented a single sign-on solution called "ComSec." You are working on the SRS that describes a future system that will utilize "ComSec" for all its user authorization and entitlement. Now, you might choose to describe user authentication and entitlement use-case like this: "The system shall use "ComSec" as the means to user authentication and entitlement." Is this enough information to implement this requirement? For somebody who understands "ComSec" it is, but for an outsider it most definitely is not.
8. Get Formal Training
Composition of well-written Business Requirements is done via a methodology. This methodology has been studied by many people who have many years of professional experience creating software specification requirements. It is essential that you consult with their expertise either by obtaining formal training or by reading publication on the subject.
SRS documentation is a foundation for all future deliverables—test cases, design specs, and source code. SRS is also an input to such project activities as scope planning and definition, cost estimating and budgeting, human resources planning, and so on. How long does it take to modify or add a business requirement before subsequent phases of the project are initiated? No time at all. Now, imagine adding a new requirement when the project is well underway. Test cases will have to be modified, design specs revised, code re-written, user manuals and training materials updated. Thus, complete, well-written, and unambiguous SRS is a key to a successful project that is on time, on budget, and within the intended scope.
If your organization has been experiencing problems developing application that are on time, on budget, and according to client and stakeholder expectations, it might be wise to introduce some formal training. If formal training cannot be achieved, there are numerous technical books on the market to help you achieve your goals.
I hope this article will help you create better Software Specification Requirements. I say this often when I write articles of this sort, but I have to say it again: Knowing the rules is not enough to get you where you want to be. Following these rules is what gets you there.
Another important point is that the above rules are only guidelines and they often need to be broken when there is not enough time or not enough resources to complete a task.
- Software Requirements, 2nd Edition by Karl E. Wiegers (Microsoft Press, 2004)
- Mastering the Requirements Process, 2nd Edition by Suzanne Robertson and James Robertson (2006)
- Writing Effective Use Cases by Alistair Cockburn (2000)
About the Author
Aleksey Shevchenko has been working with object-oriented languages for over seven years. For the past four years, he has served as a technical lead and a project manager. Aleksey has been implementing Enterprise IT solutions for Wall Street and the manufacturing and publishing industries.
Page 3 of 3