What Makes a Great Software Requirements Specification?

What Makes a Great Software Requirements Specification?

There are many good definitions of System and Software Requirements
Specifications that will provide us a good basis upon which we can both define a
great specification and help us identify deficiencies in our past efforts. There
is also a lot of great stuff on the web about writing good specifications. The
problem is not lack of knowledge about how to create a correctly formatted
specification or even what should go into the specification. The problem is that
we don't follow the definitions out there.

We have to keep in mind that the goal is not to create great specifications
but to create great products and great software. Can you create a great product
without a great specification? Absolutely! You can also make your first million
through the lottery – but why take your chances? Systems and software these days
are so complex that to embark on the design before knowing what you are going to
build is foolish and risky.

The IEEE (http://www.ieee.org/) is an excellent
source for definitions of System and Software Specifications. As designers of
real-time, embedded system software, we use IEEE STD 830-1998 as the basis for
all of our Software Specifications unless specifically requested by our clients.
Essential to having a great Software Specification is having a great System
Specification. The equivalent IEEE standard for that is IEEE STD 1233-1998.
However, for most purposes in smaller systems, the same templates can be used
for both.

What are the benefits of a Great SRS?

The IEEE 830 standard defines the benefits of a good SRS:

Establish the basis for agreement between the customers and the suppliers on
what the software product is to do.

The complete description of the
functions to be performed by the software specified in the SRS will assist the
potential users to determine if the software specified meets their needs or how
the software must be modified to meet their needs. [NOTE: We use it as the basis
of our contract with our clients all the time].

Reduce the development effort.

The preparation of the SRS forces the
various concerned groups in the customer’s organization to consider rigorously
all of the requirements before design begins and reduces later redesign,
recoding, and retesting. Careful review of the requirements in the SRS can
reveal omissions, misunderstandings, and inconsistencies early in the
development cycle when these problems are easier to correct.

Provide a basis for estimating costs and schedules.

The description of
the product to be developed as given in the SRS is a realistic basis for
estimating project costs and can be used to obtain approval for bids or price
estimates. [NOTE: Again, we use the SRS as the basis for our fixed price
estimates]

Provide a baseline for validation and verification.

Organizations can
develop their validation and Verification plans much more productively from a
good SRS. As a part of the development contract, the SRS provides a baseline
against which compliance can be measured. [NOTE: We use the SRS to create the
Test Plan].

Facilitate transfer.

The SRS makes it easier to transfer the software
product to new users or new machines. Customers thus find it easier to transfer
the software to other parts of their organization, and suppliers find it easier
to transfer it to new customers.

Serve as a basis for enhancement.

Because the SRS discusses the product
but not the project that developed it, the SRS serves as a basis for later
enhancement of the finished product. The SRS may need to be altered, but it does
provide a foundation for continued production evaluation. [NOTE: This is often a
major pitfall – when the SRS is not continually updated with changes]

What should the SRS address?

Again from the IEEE standard:

The basic issues that the SRS writer(s) shall address are the following:

a) Functionality. What is the software supposed to do?

b) External interfaces. How does the software interact with people,
the system’s hardware, other hardware, and other software?

c) Performance. What is the speed, availability, response time,
recovery time of various software functions, etc.?

d) Attributes. What are the portability, correctness,
maintainability, security, etc. considerations?

e) Design constraints imposed on an implementation. Are there any
required standards in effect, implementation language, policies for database
integrity, resource limits, operating environment(s) etc.?

What are the characteristics of a great SRS?

Again from the IEEE standard:

An SRS should be

a) Correct

b) Unambiguous

c) Complete

d) Consistent

e) Ranked for importance and/or stability

f) Verifiable

g) Modifiable

h) Traceable

Correct

- This is like motherhood and apple pie. Of course you want the
specification to be correct. No one writes a specification that they know is
incorrect. We like to say - "Correct and Ever Correcting." The discipline is
keeping the specification up to date when you find things that are not
correct.

Unambiguous -

An SRS is unambiguous if, and only if, every requirement
stated therein has only one interpretation. Again, easier said than done.
Spending time on this area prior to releasing the SRS can be a waste of time.
But as you find ambiguities - fix them.

Complete -

A simple judge of this is that is should be all that is needed
by the software designers to create the software.

Consistent -

The SRS should be consistent within itself and consistent to
its reference documents. If you call an input "Start and Stop" in one place,
don't call it "Start/Stop" in another.

Ranked for Importance -

Very often a new system has requirements that are
really marketing wish lists. Some may not be achievable. It is useful provide
this information in the SRS.

Verifiable -

Don't put in requirements like - "It should provide the user
a fast response." Another of my favorites is - "The system should never crash."
Instead, provide a quantitative requirement like: "Every key stroke should
provide a user response within 100 milliseconds."

Modifiable -

Having the same requirement in more than one place may not
be wrong - but tends to make the document not maintainable.

Traceable -

Often, this is not important in a non-politicized
environment. However, in most organizations, it is sometimes useful to connect
the requirements in the SRS to a higher level document. Why do we need this
requirement?

What is the difference between a System Specification and a Software
Specification?

Very often we find that companies do not understand the difference between a
System specification and a Software Specification. Important issues are not
defined up front and Mechanical, Electronic and Software designers do not really
know what their requirements are.

The following is a high level list of requirements that should be addressed
in a System Specification:

• Define the functions of the system
  
• Define the Hardware / Software Functional Partitioning
  
• Define the Performance Specification
  
• Define the Hardware / Software Performance Partitioning
  
• Define Safety Requirements
  
• Define the User Interface (A good user’s manual is often an overlooked part
  of the System specification. Many of our customers haven’t even considered that
  this is the right time to write the user’s manual.)
  
• Provide Installation Drawings/Instructions.
  
• Provide Interface Control Drawings (ICD’s, External I/O)

One job of the System specification is to define the full functionality of
the system. In many systems we work on, some functionality is performed in
hardware and some in software. It is the job of the System specification to
define the full functionality and like the performance requirements, to set in
motion the trade-offs and preliminary design studies to allocate these functions
to the different disciplines (mechanical, electrical, software).

Another function of the System specification is to specify performance. For
example, if the System is required to move a mechanism to a particular position
accurate to a repeatability of ± 1 millimeter, that is a System’s requirement.
Some portion of that repeatability specification will belong to the mechanical
hardware, some to the servo amplifier and electronics and some to the software.
It is the job of the System specification to provide that requirement and to set
in motion the partitioning between mechanical hardware, electronics, and
software. Very often the System specification will leave this partitioning until
later when you learn more about the system and certain factors are traded off
(For example, if we do this in software we would need to run the processor clock
at 40 mHz. However, if we did this function in hardware, we could run the
processor clock at 12 mHz). [This implies that a certain level of research or
even prototyping and benchmarking needs to be done to create a System spec. I
think it is useful to say that explicitly.]

However, for all practical purposes, most of the systems we are involved with
in small to medium size companies, combine the software and the systems
documents. This is done primarily because most of the complexity is in the
software. When the hardware is used to meet a functional requirement, it often
is something that the software wants to be well documented. Very often, the
software is called upon to meet the system requirement with the hardware you
have. Very often, there is not a systems department to drive the project and the
software engineers become the systems engineers. For small projects, this is
workable even if not ideal. In this case, the specification should make clear
which requirements are software, which are hardware, and which are
mechanical.

What is the difference between a design requirement and software
requirement?

In short, the SRS should not include any design requirements. However, this
is a difficult discipline. For example, because of the partitioning and the
particular RTOS you are using, and the particular hardware you are using, you
may require that no task use more than 1 ms of processing prior to releasing
control back to the RTOS. Although that may be a true requirement and it
involves software and should be tested – it is truly a design requirement and
should be included in the Software Design Document or in the Source code.

Consider the target audience for each specification to identify what goes
into what documents.

Marketing/Product Management

Creates a product specification and gives it to Systems. It should define
everything Systems needs to specify the product

Systems

Creates a System Specification and gives it to Systems/Software and
Mechanical and Electrical Design.

Systems/Software

Creates a Software Specification and gives it to Software. It should define
everything Software needs to develop the software.

Thus, the SRS should define everything explicitly or (preferably) by
reference that software needs to develop the software. References should include
the version number of the target document. Also, consider using master document
tools which allow you to include other documents and easily access the full
requirements.

Is this do-able? Won’t we miss our deadlines if we take the time to do
this?

This is a great question. There is no question that there is balance in this
process. We have seen companies and individuals go overboard on documenting
software that doesn’t need to be documented, such as a temporary utility. We
have also seen customers kill good products by spending too much time specifying
it.

However, the bigger problem is at the other end of the spectrum. We have
found that taking the time up front pays dividends down stream. If you don’t
have time to specify it up front, you probably don’t have the time to do the
project.

Here are some of our guidelines:

• Spend time specifying and documenting well software that you plan to keep.
  
• Keep documentation to a minimum when the software will only be used for a
  short time or has a limited number of users.
  
• Have separate individuals write the specifications (not the individual who
  will write the code).
  
• The person to write the specification should have good communication skills.
  
  
• Pretty diagrams can help but often tables and charts are easier to maintain
  and can communicate the same requirements.
  
• Take your time with complicated requirements. Vagueness in those areas will
  come back to bite you later.
  
• Conversely, watch out for over-documenting those functions that are well
  understood by many people but for which you can create some great requirements.
  
• Keep the SRS up to date as you make changes.
  
• Approximately 20-25% of the project time should be allocated to requirements
  definition.
  
• Keep 5% of the project time for updating the requirements after the design
  has begun.
  
• Test the requirements document by using it as the basis for writing the test
  plan.