Best Practices - Specification Document

Best Practice

Title Page

1.0 Introduction

2.0 Specifications

2.1 Problem Domain

2.2 Query Specifications

2.3 Behavioral Rule Specifications

2.4 Mapping Specifications

2.5 Operations Specifications

3.0 Deprecated Specifications

4.0 Glossary

5.0 Change Log

Template Specifications Document

Example Specifications Document

Rationale

A Specifications Document contains interface specifications for the interface between the Problem Domain and the software program, library, file protocol, etc.

The purpose of writing Specifications Documents is:

A Specifications Document is used by Design Document writers and implementers to ensure accurate communication of interfaces between the various components of a project and the between the project and the top level problem domain

This software practice document is largely based on the book "Practical Software Specifications", by Benjamin L. Kovitz, Manning Publications Co., 1999. Please refer to this book or other books covering the content and style of specification documents.

Best Practice

The remainder of this document contains the Best Practices for writing a Specifications Document.

Each Specification Document must be written in Microsoft Word format using Microsoft Word.

The text of the document must be written in the present tense and third person. Do not use the words 'will', 'I' or 'you'.

The name of each Specification Document should match the title of the document (without the spaces). It is important to include the project name and subproject (or program/library name) and the word 'Specification' or the abbreviation 'Spec'. Example: 'ACECommandParserSpec.doc'.

The contents of the Specifications Document must include, but is not limited to, the following sections:

 

Title Page

The title page must contain the title of the document, document preparer's name, version number and date of creation or revision of the document. Also contained on the title page, near the bottom, is the copyright notice.

The form of the title must be "<ProjectName><TaskName>Specification". The ProjectName can be the initials of the project. The TaskName can be a subproject name, program name or library name. Example: 'ACE Command Parser Specifications'.

The version number of the document usually starts with 0.X during initial development of the document. Each revision of the document that is reviewed by the project developers should have successive minor numbers (example: 0.1, 0.2, 0.3, etc). When the document is complete and ready for Design Document writers to use the version must be set to 1.0. Each minor revision of the document would increment the minor number (example: 1.1, 1.2, 1.3, etc.). For any major change in the document the major number must be incremented (example: 2.0).

The copyright notice must appear on each Specifications Document generated. By default the 'All Rights Reserved' copyright notice is used.

Table of Contents

The table of contents is on its own page directly following the title page.

The table of contents to be used is generated automatically by Microsoft Word. Under the 'Insert' pull down menu select the 'Indexes and Tables' item. Select the 'Table of Contents' tab and select the 'Formal' table format.

1.0 Introduction/Overview

The introduction is composed of several paragraphs that tell the read what the document is and where it fits into the project documentation with respect to other documents and where the Interface Specification fits within the project architecture.

The first paragraph gives the name of the interface that is specified in the document and describes the purpose of the interface. In addition the first paragraph describes where the interface fits into the project architecture (ie. What piece of software is 'inside' the interface and what outside piece(s) of software use the interface).

The second paragraph refers to any requirement numbers that the whole document satisfies. If individual specifications within the document satisfy requirements then the requirements are referred to in the individual specifications.

The third paragraph lists the documents that this document is derived from. Typically this includes architecture design documents and more general specification documents. In addition this paragraph lists specification documents that are derived from this document.

The last paragraph of the introduction must briefly describe the structure of the document. For each major section in the document, name the section and provide one or two sentences that describe the contents of the section.

Summary:

1.1 Notation

Any special notations used in the document that are not intuitive must be described in this section. Example:

Each individual specification in the Specification Document must have an identifier. The identifier is of the form 'S-XXX' where XXX is a dotted number. The number shall consist of the specification's section number the specification is in plus a dotted number. Specification identifiers are used in Design Documents and source code to refer to specifications in the Specifications Document. An example of a specification follows:

S-2.1.3 The name of the control program shall be 'bamboozel'. The program takes no arguments.

2.0 Specifications

Specifications are descriptions of interfaces. Interfaces can be between the software and the user, files, sockets, pipes, shared memory, semaphores, and library/driver APIs. These interfaces are visible from outside the software domain. Interfaces within the software domain are not included in this document. A software domain may be divided into components where each component has an interface. When specifying the interface to the component everything outside the component, including other components, is the component's problem domain.

An example of a software domain is a library where the API is the externally visible interface. All programs and libraries that use the library are in the Problem Domain.

Subsections:

The Problem Domain description is placed in the 'Problem Domain' subsection.

The specifications may be split up along the same lines as the requirements in the Requirements Document:

  1. Problem Domain
  2. Query Specifications
  3. Behavioral Specifications
  4. Mapping Specifications
  5. Operations on Software Specifications

An example of an alternate set of subsections follows:

  1. User Interface
    1. Graphical interface
    2. Command line Interface
  2. Databases Quarry Interface
  3. Network Communication Interface

If the recommended specification subsections are used but there are specifications that do not fit into the categories of the sub sections then appropriate additional subsections must be created for the specifications.

Individual Specifications:

Each individual specification must have an identifier. The identifier is of the form 'S-XXX' where XXX is a dotted number. The number shall consist of the specification's section number the specification is in plus a dotted number. Specification identifiers are used in Design Documents and source code to refer to specifications in the Specifications Document. An example of a specification follows:

S-2.1.3 The name of the control program shall be 'bamboozel'. The program takes no arguments.

After the initial release of a Specifications Document, version 1.0, specifications may NEVER be renumbered. This Best Practice exists to prevent having to change other documents that refer to specifications by number (as they must).

At times it is necessary to add new specifications to a Specifications Document after the initial release, version 1.0. If there are additional specifications placed between existing specifications then the specification id of the new specifications must have letters appended to the specification id of the preceding specification. Example: If a new specification is added immediately after specification S-2.1.3, the identifier of the new specification is S-2.1.3a.

Once an initial Specifications Document has been released, version 1.0, the text of any deleted specifications shall be replaced with the word 'Deprecated'. This prevents reuse of specification identifiers and confusion in documents that refer to specifications. The text of deprecated specifications is moved to the deprecated section of the document for historical purposes.

An existing specification may be modified but must continue to apply to the same effect. Valid changes include but are not limited to quantities, qualities and names within the specification.

Interface Types:

Although the following list of interface types is not exhaustive, it does include the more common interfaces found in an Interface Specification Document.

APIs - An Application Program Interface (API) consists of a description of the declarations of a group of public functions, typically in a single library, that an application can use to carry out it's task. The descriptions of the declarations of internal functions (private functions) in a library are not part of the API. The main parts of a declaration description include the following:

Synopsis:

Include a brief description of the purpose of the function.

Declaration

Show the declaration of the function in the language it is to be implemented. example:

void ComputeTheWorld ( class WorldAttributes attributes, double accuracy, class WorldAnswers answer)

[ Arguments ]...

For each argument in the declaration, describe the argument including its purpose in the function plus the following:

[ Return ]

For the return value, describe its meaning and its value limits. If the function has side effects, the side effects should be described here.

[ Exceptions ]

If the function can throw exceptions, each of the exceptions that can be thrown must be listed and under what circumstances the exception can be thrown.

File Formats - When an application uses files for input or output the format of the files must be described. For ASCII files the syntax and semantics must be described. For binary files the fields in each record type must be described.

User Interfaces: Command Lines - Command lines for applications must be described. The description is very similar to the description for API function declarations.

User Interfaces: Graphical - For graphical user interfaces each window and dialog must be described. Each menu item, button, icon, text field, drawing areas and their interactions must be described.

Protocols - For network and serial device communications a protocol is required. If the software uses a special purpose protocol the protocol must be described.

2.1 Problem Domain

The first paragraph must describe what a problem domain is in general. See the template specification.

The following paragraphs describe the problem domain specific to this document.

The Problem Domain should be fully described in a Requirements Document. This section may contain a brief review of the Problem Domain interfaces with the Software Domain.

2.2 Query Specifications

This section defines query formats and responses. Query information from the software domain is requested by the Problem. The information sent to a Problem Domain may utilize data placed in the query by the Problem Domain actor making the request.

Queries can include the following:

 

See the Requirements Best Practices document for a description of a query.

2.3 Behavioral Rule Specifications

This section defines the interfaces for controlling problem domain objects.

The Requirements Best Practices document describes Behavioral Rules.

 

2.4 Mapping Specifications

This section defines the interfaces for controlling Problem Domain objects.

The Requirements Best Practices document describes Behavioral Rules.

2.5 Operations On Software Specifications

This section contains only interface specifications for operations problem domain actors perform on the software. Example: any data objects that are contained only within the software and may have operations performed on them by the user would have the user interfaces for the operations described here.

This section differs from the Query Specification in that Query Specifications are for information that the software obtains from Problem Domain objects or obtains from current internal representations of Problem Domain objects.

The Requirements Best Practices document describes Operations on Software.

3.0 Deprecated Specifications

Specifications that are removed from the Specifications section after the initial release are moved to this section. This provides a history of changes to the document and also allows the maintainer of Design Document to track the disposition of specifications in these documents.

4 Glossary

A list of definitions of terms used in this document.

5 Change Log

Each change of this document after the initial release must be described in this section along with the version of the document and the date of the change.

Version

Date

Person

Reason

0.1

Sep 1, 2000

Leon S. Searl

Initial working version.

 


Leon S. Searl