![Guidelines to Writing a Clear Spec [Software Specification Document]](https://blog.soshace.com/wp-content/uploads/2019/09/Writing-a-Clear-Spec.jpg "Guidelines to Writing a Clear Spec [Software Specification Document]")
Writing a clear and crisp product/software requirement specification is crucial and pivotal to the success of any software project. And while every company has its own template and requirements for what to include in the product/software spec, there are some underlying principles and key features, which are pretty universal — all projects or products need to have all the details and requirements for the engineering team to create the desired product, and in case the coding or blueprints get lost, engineers should be able to recreate the project from scratch using the specification document.
In this article, we’ll clearly define what a spec is, why you need it, what you should include in the requirements, and finally, how to write an adequate spec that will help your engineering team.
While some software engineers might argue that writing tech specs could be a waste of time and potentially impede the agile development process, others find specs as opportunities to sit back and think through some complicated issues surrounding the development in order to avoid making mistakes and wasting precious time. The former thinking is inherently harmful, the latter – will help you get better at solving problems and grow professionally.
Spec definition: what is software requirement specification?
A requirement spec is a well-defined definition of what a product/software is or does. The set of the requirements, which you define in your product spec, will be used as inputs in the design stages of product development. The purpose of the document is to describe the behavior and functionalities of software in a specific environment as detailed as possible.
Why do we need a software requirement specification document?
You need a software requirements specification doc (hereinbelow, might be referred to as SRS) in order to improve the accuracy of your estimates and proposed development timelines, predict and correct operational and other costs, prevent security problems, provide documentation for future teams or novices, avoid plausible risks, and finally, above all — ship the right product with better quality and speed.
By writing a clear spec well in advance, you’ll raise the quality of your decision, reduce the chance of surprises, improve communication between different teams and team members, and raise accountability by publicly announcing the commitment to measurable goals and outputs.
A written communication, especially in the engineering environment, is far superior to spoken, because it’s consistent, can be referred to in the future, and raises your team’s awareness of the work they are about to do.
What do you need to do before creating a software requirement spec?
Before you even sit down to write your software spec, you’ll need to heavily prepare to make your job easier. The preparation stage can be further divided into four distinct steps:
- Elicitation
- Analysis
- Definition
- Specification
Let’s address each step in more detail.
Elicitation principally means gathering the requirements from stakeholders. Usually, it’s done by the senior managers who negotiate priorities, concerns, and needs of the stakeholders.
An analysis involves checking for consistency and completeness of the gathered requirements. Since the focus of any development works should be on the user and user experience, the analysis should clearly define what user goals are required and optional, measurable or vague, singular or mixed (meaning that one requirement, in fact, contains multiple other requirements, and if that’s the case, each one shall be separated and described singularly whenever it is possible).
The definition step means writing down the requirements for developers. Herein, you must agree on the users of your system, their terminology, working environment, and workflow.
Specification means creating the first stepping stone of a bridge between developers and designers. During this step, you’ll work with both designers and developers in construing the actual system that will meet the needs of the end-users.
SRS categories
Requirements show the structures and functions necessary for a particular product. Thus, the requirements are placed into two separable categories:
- Functional — describe the functions that the system must execute
- Structural — describe the constraints, denote how well the system performs the functions: availability, testability, maintainability, and ease-of-use.
How to write a functional specification document for software [what’s included in functional spec]?
The functional spec can be a full-fledged document on its own or a part of a larger SRS document that specifies what functions a system or software must perform. Since more often than not, a functional spec is a part of an SRS, it provides a more technical response to matching requirements in the document, picking up the results from the requirements analysis stage.
Functional specs do not define the system or describe how the system functions will be implemented. Instead, its focus is on the outside agents (read: end-users) that come in contact or interact with software. Basically, functional requirement spec describes an interaction of the user with the system/software.
For example, ‘when the user clicks on Ok button, the dialog window closes, and the user returns to the main window, which is in the state it was before the dialog window was displayed”
This way, it’s obvious that a functional spec describes each of the possible user inputs and the program response actions.
There are at least four main purposes for functional specs: to achieve team consensus on what the program does before the actual coding begins, to let developers know exactly what to build and testers what to test, and finally inform the stakeholders on what they are about to get after the development works are finished.
After the functional spec is signed off, the team starts coding and then testing and then checking the results and outcomes of the works against the functional spec.
There are many methods to arrive at a functional requirements spec, among the most common and popular is drawing or rendering wireframes and graphically designed UI screenshots. After the drawings and graphics are approved by the team and the stakeholders, the graphic elements are numbered and written down with explanations per each number and drawing, so that developers and testers can later check if the intended functionality works as expected.
There could be many elements to a functional spec document depending on the size of the project, type of industry, and, finally, the internal procedures agreed on with a company; however, the typical functional spec includes
- Project scope, that is the project’s goals, features, tasks, costs, etc
- Risk and assumptions, which could affect the functional design of the product
- Product overview, which explains how the software solves the user’s problem
- Use cases, where the functional requirements are placed in the context of a user’s actions.
- Requirements which cover the features of the product and explain them
- Configuration explains what a user needs to do in order to start using software
- Non-functional requirements — the features of the product that are not core
- Error reporting that explains how the product handles errors and exceptions
There are also quite a few formats for a functional spec, which can come as a part of
- Business requirements document, which describes the high-level goals of an organization and how they are about to be achieved
- System requirements document, which encompasses functional and non-functional requirements, as well as any use cases that the software must fulfill
- Functional requirements document describes exactly how the system or software should function to meet the requirements of business and system requirements documents.
Functional specs can also be presented in the form of use cases or user stories. Perhaps, the most popular is the use case format, which typically represents a series of steps, describing user actions and the system response. User story format looks at the product not from the system’s response perspective but from the user, and usually comes down to the following syntax: ‘As an end-user I can do this so I receive this’ or, making a more illustrative example, ‘As a participant of the course program, I can view other people’s responses on the discussion thread, respond and receive comments back.’
See examples of functional specs in the Resources section of this article.
How to write a structural specification document for software [what’s included in a non-functional spec]?
A structural specification document, best known as a non-functional spec, defines the requirements or attributes of the system that don’t actually do anything but are still important for the viability of the system. Among non-functional requirements can be some quality attributes of the system, such as performance, security, usability, compatibility, and so on, attributes which do not represent special features of the product, but are nevertheless extremely important.
Each requirement must be objective and quantifiable (there must be a measurable way to assess if the requirement is met).
Below are some examples of non-functional requirements:
- Performance (resources required, response time, throughput, transaction rates, etc)
- Operating constraints (system resources, people, required software, etc)
- Platform constraints
- Accuracy and Precision (requirements about accuracy and precision of data)
- Modifiability (effort required to change the software often expressed in personnel effort, person/month)
- Portability (effort required to move the software to a different platform)
- Reliability (how often software fails in MTBF (mean time between failures))
- Security (requirements on protection of system and data)
- Usability (how difficult it’s to learn the software for the user)
- Legal issues (intellectual rights, privacy, the export of restricted technologies, etc.)
Examples of good and bad non-functional specs can be viewed in the Resource section of this article.
Writing a software specification document: guidelines
Again, as being said earlier, SRSs vary greatly across companies and industries, however, there are still some commonalities in its structure that couldn’t be ignored and need to be accounted for.
Example structure of a requirement spec {as seen on Wiki}:
Purpose
- Definition
- Background
- System Overview
Description
Product perspective
- System interfaces
- User interfaces
- Hardware interfaces
- Software interfaces
- Communication interfaces
- Memory constraints
Design constraints
Product functions
User characteristics
Constraints, assumptions, and dependencies
Specific requirements
External interface requirements
Functional requirements
Performance requirements
Logical database requirement
Software System Attributes
- Reliability
- Availability
- Security
- Maintainability
- Portability
Functional requirements
- Functional partitioning
- Functional description
- Control description
Environment characteristics
- Hardware
- Peripherals
- People
So, let’s summarize everything above and outline what constitutes a good system’s requirements. A good requirements spec must answer the following questions:
- What does your software do?
- How does your software behave?
- What are the requirements for your software to operate without interruptions?
- Are there any other requirements or constraints that should be accounted for when developing, testing, and deploying your software?
The general structure, therefore, must contain the following sections:
- Introduction: a clear and concise description of the product written and agreed on together with the stakeholders and the development team, which addresses the core questions like why software needs to be built, what it should and should not do. This section can end with a brief overview of what’s expected from the entire document, any references to other materials that need to be consulted in order to understand the full scope of the works.
- Description: an explanation of different product functionalities including definitions of hardware interfaces and user interfaces, among other important requirements that define the general functionalities of the product.
- Specific requirements (functional requirements): the functionalities that were mentioned in the description should be enumerated and explained in great detail here, describing all user inputs and expected outputs or system responses.
- Non-functional requirements: description of quality attributes that are not directly related to the functionality of the product but are important for its successful operation.
Since SRS is used by many (if not all) team members, it’s important that the document would be easily understood by all concerned parties, therefore, it’s imperative to clearly define all the terms that might sound foreign or ambiguous for some team members. It’s also quite important to separate software requirements and technical implementations, meaning the needs and how these needs are going to be implemented should be kept separate.
All the requirements must be complete and do not lead to misunderstanding and different interpretations. Hence, it’s important to pay close attention to the language of the SRS, which we’ll address in the next section.
A note on the language of SRS
These guidelines would not be complete without a little recourse into the language of writing the spec.
First of all, let’s look at the key characteristics of any good requirements document:
- All language must be unambiguous: instead of vague wording use concrete words and examples.
- The writing should be concise: write for the reader in mind, convey the essence of what’s required.
- Be consistent: do not contradict requirements within the document.
- The writing should be complete: the reader doesn’t have to look for any additional resources to understand what’s being written.
- Avoid redundancy: do not repeat yourself, rather — provide a reference for it being already said within the document.
Developers and stakeholders need to see an exact, clear and organized prose with tables, diagrams, bullet points, and testable statements.
When writing, use Subject + Auxiliary Verb + Main Verb + Object formula whenever it is possible. Auxiliary verbs that should be used are “must” and “will” for commands and “must not, cannot” for prohibitions, these are called strong auxiliary verbs. Avoid using weak suggestions, generalities, and ambiguous words that are often denoted by the use of the following weak auxiliary verbs, such as “should, shall, may” and adjectives, such as “small, big, easy, hard, friendly,” and so on. Overall, commands and prohibitions should be short, use active and strong verbs. Again, as with any writing, passive voice should be excluded entirely.
Read more on the language of SRS in the Resources section below.
Resources:
Software Requirements Specification Template:
SRS Template from ProjectConnections
IEEE Software Requirements Specification Template {doc file}
Software Requirements Specification (SRS) Template – UCCS {doc file}
Software Requirements Specification Example:
IEEE Software Requirements Specification Example – Gephi {pdf}
Software Requirements Specification – IBM {doc file}
SRS Example Michigan State University {doc file}
Functional Specifications:
Functional Specifications Template Standford University {doc file}
Functional Specifications Example National Academies {pdf file}
Example of Use Case Format of Functional Specifications University of Texas {pdf file}
Example of User Story Format of Functional Specification
Structural Specifications (non-functional):
Quality Attributes Example California Polytechnic State University
Requirement Statements and Their Critique California Polytechnic State University
Advice on the language of SRS:
Writing Effective Requirements Specifications by NASA
Key words for use in RFCs to Indicate Requirement Levels – Harvard University
Plain Language Guidelines from the US Government
