Goal of this template
The goal of this template is to provide useful suggestions for the documentation of software requirements in a development project.
Requirements of a software system may be documented, or not. There may be many reasons not to document software requirements, but we don't need to discuss it here. This template is for those who need to document requirements.
Software requirements may be documented in different ways. There is not a single universal standard for documenting requirements.
The documentation of requirements is usually more or less formalized depending on the criticality of the product to be developed.
If your product is life critical, that is if a software malfunction may harm people, you need a very thorough and formalized management of software requirements. In this case, don't use this template. This template is intended for use in non-life-critical software projects.
If you already use or need to use another - internal or industry-specific - existing type of document or template, I hope you will anyway find in this template some useful suggestion. For people involved in an already started project, or maintaining an existing software system, the template may also be used as a checklist for missing aspects.
The template does not contain any specific treatment of contractual aspects (rules governing the client-supplier relationship) and validations (acceptance by the client and other stakeholders of a specification), because these characteristics depend on the specific organizational contexts, and can't be treated in general terms.
Structure of the template
This template is a composition of various sections. Each section can be a separate document, or remain just a section of the single composite document. Each section may be more or less formalized, depending on your needs and preferences. What's more, each section may be used or not used, again depending on your needs and preferences.
The main sections are:
- Vision
- Release Plan
- Software requirements specification
- Glossary - Data Repository
The Vision is a high level system specification. In its simplest form, it may be a two-pages product data sheet. In its most complex form, it may be a 20 pages executive-level system description.
It is the main communication medium among stakeholders about the work to be done. It contains no details.
The Release plan specifies the releases planned for the system, and other high-level milestones if significant for the client.
Whenever possible, it is a good strategy to build and ship the system incrementally, according with client's priorities and system's architecture. The release plan can and must be changed, whenever client and developers need to change it.
Every project, even the smallest and most informal one, gets benefits from having a vision and a release plan.
Every project, but the most informal ones, needs some form of Software requirements specification, in order to document the shared understandings between client and developers. Depending on needs and preferences, the software requirements specification may be more or less formal, and it may contain every detail or just the most significant points of agreement.
The most common elements that constitute a software requirements specification are:
- A set of user stories, or use cases. User stories are small chunks of system functionality; use cases are more complete operational scenarios of system usage. User stories are short, and may correspond to a single atomic functional requirement (see below) ; use cases may be longer because they describe end-to-end usage scenarios.
- A list of atomic requirements (“the system shall...”). Some of them specify a system functionality, and are called functional requirements. Others specify other types of characteristics for the system (like usability, performance, reliability level, internationalization) and are called non-functional requirements, or quality attribute requirements.
The form of the specification may vary from the most informal (index cards for user stories to post on a wall) to the formal (several documents with hundreds or thousands of pages).
The Glossary - Data Dictionary section deals with information and data. It may be specified at different complexity levels, depending on actual needs.
A Glossary is an often informal list of terms and definitions. It defines a common language, the minimal basis for mutual understanding in a project.
A Data Dictionary is a structured repository of data definitions, which specifies structures and relationships of data.
Who, when and how (to use the template)
In the tradition of software development, the role which has the responsibility to document requirements is called “analyst”. In actual organizational contexts and situations, this role may be fulfilled by people with different labels.
The timing of the specification depends on the software development process used. Old “waterfall” methods require the specification of all detailed requirements upfront, and a global client validation (client signature) before development begins.
Iterative and agile methods suggest a just-in-time approach to requirements management. Partial sets of requirements (say, those concerning a specific system functionality) are detailed just before their implementation, in order to make as short as possible the cycle of definition-build-test, and to reduce the risks and the impacts of misunderstandings and reworks.
In these contemporary approaches, the software requirements specification may be created and validated incrementally. It is a growing mosaic, not a monolith.
But all requirements are not equal. While just-in-time requirements definition works effectively for functional requirements, it may be dangerous for non functional requirements, because a late discovery of a non functional requirement (say, related to internationalization, or portability, or security) may cause extensive rework. When it is possible, it is far better to clarify non functional requirements at the beginning of a project.
Author: Adriano Comai – www.analisi-disegno.com
This template is licensed under a Creative Commons Attribution-Non-commercial 3.0 Unported License.