[Before you give the page a look like "why is there an image of a girl?" on this page, simply stated, software requirements specifications on the contrary
are a very unsexy part of the software development lifecycle, but they ARE a necessary evil and become a make-or-break element for all software projects.]
What are software requirements specification (SRS)? Software requirements specification capture system behavior as opposed to non-functional requirements specifications which define attributes as not behavior. This 'functionality' refers to services, tasks or functions the user performs using the system in question.
In product development, it is important to understand the difference between the baseline functionality necessary for any system to compete in that product domain, and features that make the system different from their competitor's products.
Some strategies have important implications for software architecture. Specifically, it is not just the Software requirements specifications of the initial release that must be supported in the architecture. The Software requirements specifications of initial products need to be explicitly taken into consideration.
The key to this blog posting is to get a complete understanding of Software requirements specifications, not technical specifications which are easy to confuse. Here is the difference.
1. A software requirement specification describes how a product will work entirely from the user's (or customer's) perspective. It should care less about implementation. (e.g. the 'what' v. the 'how')
2. A technical specification describes the internal implementation of the software. It talks about data structures, relational database models, choice of programming protocols, and environmental properties.
So before we continue, please remember that this blog post is about Software requirements specifications as opposed to technical specifications.
1.2 Use Cases
It is important to understand the difference bewteen a software requirements specification and a use case. While they both define behavior, the use case tells the story showing the end-to-end scenario. To further define, a use case defines a goal-oriented set of interactions between external actors and the system under consideration. Actors are parties outside the system that interact with the system. A primary actor has the goal requiring the assistance of the system. A secondary actor is one from which the system needs assistance.
Generally, use case steps are written in an easy-to-understand structured story using the verbage of the domain. This is engaging for users who can easily follow and validate the use cases, and the accessibility encourages users to be actively involved in defining the Software requirements specifications.
2.1 The importance of Software Requirements and Specifications
Most web site projects include a body of information that describes the product or the project deliverables which deals with the objectives of the final product, defined in the project requirements (or Software requirements specifications), and any rules for creating the product, defined in the project specifications.
A key benefit of developing a software requirement specification is in streamlining the development process. The developer working from the software requirement specification has, ideally, all of their questions answered about the application and can start to develop. Since this is a functional specfication that was client approved, they are building nothing less than what the customer wants. There should be nothing left to guess or interpret when the functional spec is completed. This is the brilliance of the software requirement specification.
2.2 Requirements Define Critical Objectives
A software requirement specification is an objective that must be met. The customer or product team define most software requirements in functional terms, leaving design and implementation details to the developers. They may specify price, performance, and reliability objectives in fine detail, along with some aspects of the user interface.
Because there are so many types of requirements, the term requirement is odd because it describes the concept of an objective or goal or necessary characteristic, but at the same time the term also describes a kind of formal documentation, namely the requirements document. Putting aside the particular document for now, Software requirements specifications are instructions describing what functions the software is supposed to provide, what characteristics the software is supposed to have, and what goals the software is supposed to meet or to enable users to meet. A set of Software requirements specifications would include documents spelling out the various requirements for the project -- the "what" -- as well as specifications documents spelling out the rules for creating and developing the project -- the "how" or implementation specifications.
Project requirements provide an obvious tool for evaluating the quality of a project, because a final review should examine whether each requirement has been met. However, it's often never quite that simple. Requirements tend to change through the course of a project, with the result that the product as delivered may not stick to the available Software requirements specifications -- this is a disturbing part of the quality assurance process. Moreover, meeting all of the requirements doesn't ensure a quality product, rather the requirements may not have been defined with an eye towards the quality of the end-user's experience. A project's Software requirements specifications are more useful for determining the product's quality.
2.3 Specifications Define How to Meet The Objectives
A software requirement specification is literally the conversation of a specific point. It's difficult in this instance to avoid the circular reference. A project's specifications consist of the body of information that should guide the project developers, engineers, and designers through the work of creating the software.
A software requirement specification document describes how something is supposed to be done. A specifications document may list out all of the possible error states for a certain form, along with all of the error messages that should be displayed. The specifications may also describe the steps of any functional interaction, and the order in which they should be followed by the user. A requirements document, on the other hand, would state that the software must handle error states reasonably and effectively, and provide explicit feedback to the users. The specifications show how to meet this requirement.
Specifications may take several forms. They can be a straightforward listing of functional attributes, they can be diagrams or schematics of functional relationships or flow logic, or they can occupy some middle ground. Software requirements specifications can also be in the form of prototypes, mockups, and models.
Project specifications are much more important for determining the quality of the product. Every rule and functional relationship provides a test point.
A disparity between the program and its specification is an error in the program if and only if the software requirement specification exists and is correct. A program that follows a terrible specification perfectly is terrible, not perfect.
2.4 Who should be writing Software requirements specifications
The software requirement specification should be written by someone who is not involved in any other aspect of the project. You will want someone who is very familiar with GUI issues and web design, familiar enough with technology to know its limitations and capabilities, and someone who is a very skilled and a good writer. While writing a spec, you will spend a great deal of time imagining how a user might use a certain feature and how they may navigate their way through the software. The functional spec writer's main concern is marrying the user-experience with the various business logic's requirements of the project.
The following list describes the kinds of documents that belong to the body of requirements and specifications document. These are not all required for every software project, but they do all provide important information to the developers, designers and project managers tasked with implementing a project and to the quality assurance people and testers responsible for evaluating the implementation of the project.
3.1 User Requirements
User requirements typically describe the needs, goals, and tasks of the user. It is encouraged that any user requirements document define and describe the end-user, and that any measurements of quality or success be taken with respect to that end-user.
User requirements are usually defined after the completion of task analysis, the examination of the tasks and goals of the end-user.
3.2 System Requirements
System requirements has two meanings. First, it can refer to the software requirements that describe the capabilities of the system with which the product will function. For example, the web site may need to run on an application server and be clustered. Second, it can refer to the requirements that describe the product itself, with the meaning that the product is a system.
There are two categories of system requirements. Software requirements specifications specify what the system must do. User requirements specify the acceptable level of user performance and satisfaction with the system. For this later definition, it is preferred to use the more general term "requirements and specifications" over the more boring "system requirements".
3.3 Software requirements specifications
Software requirements specifications describe what the software or web site should do by defining functions and high-level logic. If the user requirements are written for the requestor and not the end-user, the user requirements are combined with the Software requirements specifications.
3.4 Software requirements specifications
Functional specifications describe the necessary functions at the implementation level. These specifications are typically used to build the system exclusive of the GUI.
With respect to a web site, a unit is the design for a specific page or category of page, and the software requirement specification would detail the functional elements of that page or page type. For example, the design for the page may require the following functions: shopping cart page, opt-out email section, context-sensitive navigation elements. These aren't GUI issues so much as they are "functionality" issues. A component is a set of page states or closely related forms of a page. For example, a component might include a submission page, and the acknowledgement page.
The Software requirements specifications document might have implications about the design of the user interface, but these implications are typically superceded by a formal design specification and/or prototype.
3.5 Design Specifications Define The Information Flow
Diagram the organization of the information (i.e., data flow diagrams). Designing flowcharts can be very handy when trying to work through a lot of information. Anything you develop now will change over time, but you'll want a thorough flowchart of the application included with your software requirement specification. Also include the navigational path through the information on this diagram. Visio is an awesome tool for developing technical diagrams and flow charts such as these.
Create a prototype
A prototype of a web application is a set of static html pages put together to show the key pages of the application and the GUI. It allows the software requirement specification writer to have something close to a working model to test their ideas out on, start focusing on the layout, and begin gathering input about the look and feel. In the iterative process, it helps to have this grand view look at a potential finished product while also seeing how the components of the system affect the overall product. Instead of boxes and arrows, bulleted comments, and a list of functions, you have an actual web page to look at and experience. Whether you create a prototype now or later, you should definitely have one before you start writing the actual software requirement specification. Aside from being a convenience for you and allowing you to possibly iterate your design much faster, it allows your team members and stakeholders the opportunity to look at the application and deliver much more specific and useful input about what you are doing. Not everyone can look at an informational flowchart and realize something is way they want it. Most people can when looking at a prototype.
Essentially, what you are doing at this stage is defining the relationships of the objects in your designer's model. You are laying the groundwork for what will become the structure of your application.
Create A Design Document
As stated in the previous section, a design document serves to collect everything we know about the application at this point into a kind of pre-software requirement specification document and allow people the opportunity to review it and provide feedback. You will want to use this document as a tool for building consensus and, simultaneously, managing the expectations of people about what is on the way. The key thing about design documents that you want to keep in mind is that they say little about the visual appearance of the application (aside from layout), and they say very little about the specifics of the user experience. If the software requirement specification is at the ground level, then this design is somewhere in the neighborhood of a higher level.
3.6 Technical Specifications
Technical specifications are typically written the by developers and architects, and describe how they will implement the project. The developers work from the Software requirements specifications, and translate the functionality into their actual coding implementation and methodologies.
3.7 Important Appendicies
Open Issues. It's acceptable for the first version of the software requirement specification to leave open issues. By the time the programmers start the dev process, all issues need to be resolved.
Side notes. While you're writing your software requirement specification, remember your various audiences: programmers, testers, marketing, tech writers, etc. As you write the specification you may think of useful factoids that will be helpful to just one of those groups. For example, I flag messages to the engineer, which usually describe some technical implementation detail, as "Tech Notes". Marketing people ignore those. Programmers use them. My Software requirements specifications are often full of "Testing Notes," "Marketing Notes," and "Documentation Notes."
Functional Specifications Need To Stay Current. Some programming teams adopt a "waterfall" mentality: we will design the program all at once, write a software requirement specification, print it, and hand it off to engineering and be done. Yeah Right.....
This approach is why most Software requirements specifications have such a bad reputation. People often say, "functional specs are useless, because nobody follows them, they're always out of date, and they never reflect the product." It could be because Software requirements specifications are out of date and don't reflect the product. Specifications should be updated frequently. The updating continues as the product is developed and new decisions are made. The software requirement specification always reflects our best collective understanding of how the product is going to work. The software requirement specification is only frozen when the product is code complete
The software requirement specification should not be released daily. On occasional milestones, the software requirement specification should be distributed with revision marks so that people don't have to reread the whole thing -- they can scan the revision marks to see what changes have been made.
Below are some good guidelines for what the benefits of a good Software Requirement Specification (SRS):
Congruency between the customers (stakeholders) 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 Software Requirement Specification will help the potential users to determine if the software in question adheres to their needs.
Reduce the development effort. The preparation of the Software Requirement Specification 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 Software Requirement Specification 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 Software Requirement Specification is a realistic basis for estimating project costs and can be used to obtain approval for bids or price estimates.
Provide a baseline for validation and verification. Organizations can develop their validation and Verification plans much more productively from a good Software Requirement Specification. As a part of the development contract, the SRS provides a baseline against which compliance can be measured.
Facilitate transfer.The Software Requirement Specification 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 Software Requirement Specification 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.
This is the most challenging task of the whole process. You've asked the questions, done the preliminary work, made a few mockups, and now it's just you with a blank document and a head full of ideas. Hopefully though, it's not totally blank. Throughout the initial steps, you've ideally been developing a working outline, and maybe even started writing a few sections as they bubble up. Below are a few tips for writing your software requirement specification:
By this, I mean make sure you've written about every single interaction point that exists in the product or application. Don't leave anything to guess or assume. It's quite likely that you'll come to a point where you believe you have covered everything, only to find you have left out something very obvious.
Use lots of screen shots
It's usually helpful to slice up your mockups and insert screenshots of the individual elements you may be writing about. Functional specfication docs are boring, and having visuals are invaluable. A picture is worth a thousand words, don't forget it.
Write concisely, correctly, and consistently
An economy of words will be appreciated by those who have to read your functional spec and make sense of it all. Additionally, try and break things out into logical componentsas much as possible. By writing correctly and consistently, make sure you're using proper grammar and consistent terms.
Use the tools and format most comfortable for you
As a spec writer (software requirement specification writer), you still have quite a few decisions make. What tools do you use? What format? What sort of style should you adopt? Also, you need to take into account how your software specficiation documents will be used: will they need to be online, will they frequently be merged with other documents.
Edit and ReWrite
Rewriting and editing are, literally, half the battle. When setting the timeline for your completion of the software requirement specification, always try to add a week more than you originally anticipated. What typically occurs is that something always comes up during the editing process. Change is the nature of the business and it's reflected in a software requirement specification. It is important that the software requirement specification is clean, but not perfect. Ideally, no spelling errors, no grammatical errors, no logic errors, and no mock up errors either. Why not perfect? Time is of the essence. It's better to get 'good' software released to get early feedback and make the necessary changes, than 'great' software out two weeks later. Many professionals will disagree on this point because their trained for perfection, but what they don't often realize is that markets and business change beneath their feet.
Check your table of contents
This is an obvious one, but make sure your table of contents correlates exactly with what's in your document. Edit from beginning to end at least three times after you think it is done Three times seems to usually do the trick...sometimes more is required, but never less. The first pass usually involves a lot of rewriting and renumbering, while the second pass is typically much lighter and may catch some of the obvious things you missed the first time. By the third time, you should be merely polishing and fixing very small details. 2) Have someone proofread your functional spec for you
This is optional, but I always find that it helps a great deal to have someone else read it over for you (especially if that person has a strong command of the written word).
3) Review Whether you're writing a software requirement specification for your company or for a client, you're going to have a series of people reviewing your functional spec to make sure they understand what's going to be built. Expect changes and be prepared to give reasons for why everything is written as it is. By the time you take your functional spec to any customers, it should be as close to perfect as possible. Part of the review process is working with your customers to come up with the best solution. If they feel the application will not meet their needs as specified, then find out why and offer solutions as to what can be done to meet their needs. After the review, take your notes back to the computer and make your changes while they're still fresh in your mind. Be sure to change your mockups and all related text, double check to make sure your changes don't affect other functionality, and then double check your table of contents. Prepare the software requirement specification for another review. Have everybody signoff on it once a consensus is reached.
Typically companies do not get the difference between a System specification and a Software Specification. Key issues are not defined first and System, Back-end and Software designers do not often know what their requirements are.
Below is a high level list of requirements that should be available in a System Specification:
Define the Hardware / Software Functional Partitioning
Define the functions of the system
Define the Hardware / Software Performance Partitioning
Define Safety Requirements
Define the Performance Specification
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 Diagrams
One aspect of the System specification is to address the full system functionality. Often times, some functionality is performed in hardware and some in software. The System specification is to define the full functionality and like the performance requirements, to execute the trade-offs and preliminary design studies to allocate these components to the different disciplines.
Another aspect of the System specification is to specify performance. If, for example, 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 specification will belong to the hardware. It is the goal of the System specification to provide that requirement and to execute 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. [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, most of the systems are small to medium size companies, combine the software and the systems documents. This is done because most of the complexity is in the software. When the hardware is used to meet a functional requirement, it is something that the software wants to be well defined.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 developers become the systems developers. 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.