Capture the right user requirements with these best practices for writing software specifications

by Contributor Melonfire | Jul 17, 2006 7:08:00 PM

Tags: Tools & Techniques, Word processors, Contributor Melonfire, software, specification

Takeaway: The successful design and development of a piece of software depends on capturing the right user requirements. This document explains what a successful development specification should include.

The successful design and development of a piece of software depends on capturing the right user requirements. If requirements do not exactly reflect the end user’s needs, a chain reaction of misunderstandings and mistakes will ensue, leading to a product that fails on all counts.

This is where a specification comes in. A specification describes how to meet user needs: it gives shape to the requirements, defines the quality of the product, and elaborates the product's design and interfaces.

In general, a specification can be segmented into two categories:

1. Functional specifications: These describe what the software must accomplish from the user’s point of view. For instance, the function of a word processor like Microsoft Word might be "to capture text and graphics in a particular format and save it to disk".
2. Design specifications: These describe how the software meets the requirements of the functional specifications. Using the same example, the location and function of toolbar buttons and menus would be part of the design specification for the word processor.

Here is a broad framework of what should be included in a specifications document.

1. Introduction

• Purpose and Scope: A summary of what the document contains, and what it is intended to describe.
• Intended Audience: A description of the document audience.
• Assumptions and Dependencies: A list of assumptions regarding the software and its operation, including the software environment and platform.
• Risks: Any risks or contingencies which need to be considered.
• Constraints: A list of limitations that impact the software design, including compatibility and interoperability issues, standards, minimum performance expectations and capacity constraints.
• Goals and Guidelines: The goals, rules or guidelines that govern the design.
• References: Related documents or historical data that needs to be used in conjunction with the specifications document.
• Glossary: Important terms, acronyms, or abbreviations.
• Revision History: An audit trail of how many times the document was updated, by whom, and the scope of changes.

2. Functional specification

• Product Architecture: This section explains the product architecture - process flows, system features and software product design. It should include diagrams, flowcharts or use cases/scenarios that explain the product architecture better.
• Development Methods: This provides a brief description of the method or approach used for the software design.
• Features: This section provides information on the features of the software. Typically, each feature is further marked up with the following information:
• ID: A unique identifying number for the feature
• Review Status: The status of the feature (approved or under review)
• Owner: The main point of contact for this feature
• User Groups/Roles: This section includes details about end-users and how they are likely to use the product. For each user type, there should be information about their role in the organization and which parts of the product are most significant to them.

3. Design Specification

• Interfaces: This section discusses software interfaces, user interfaces and communication protocols. For user interfaces, screenshots or explanatory diagrams are helpful to center the reader and make concepts clear.
• Policies and Tactics: This section discusses design policies that are outside the overall system operation. It might include coding conventions, software maintenance plans, compiling methods, software test plans and other such items.
• Detailed System Design: This section describes each component of the software using the following categories:
• Type: Whether a file, function, module, class or object
• Description: The semantic meaning of the component
• Functions: The chief function or behavior of the component
• Composition: A brief explanation of sub-components
• Limitations: Related constraints or limitations
• Interface: Interface design considerations
• Dependencies: A list of the resources that are required for the successful operation of the component, and a list of those components that depend on this component to operate successfully.

Note: You may also have sections on detailed sub-system design, which includes similar information as the above about sub-assemblies of the main components.

The sections listed above will vary depending on both the specific requirements of the software product and of the organization developing it. However, the basic information communicated via this document would remain largely the same. And now that you know what that information is, you can get started creating one for your next project.

Print/View all Posts Comments on this article

On a scale of 1 to 10 Mark W. Kaelin | 07/17/06

My rating of Requirement Specification TaulPall | 09/21/06