Software Engineering Standards Committee ProcedureSESC-07

Date: 31 August 1993 (Revised 9/16/94; 8/20/95; 4/22/96, 10/5/99)

Approved by: Paul Croll, Chair

Subject: Design Specification Preparation

1.Purpose

This procedure defines the purpose, content and format of the Design Specification. The Design Specification defines the design of the proposed standard (hereafter referred to as "standard"). Note that this applies primarily to new standards; revisions of existing standards do not normally require a Design Specification. The Design Specification is required only in cases where the Management Board feels it is appropriate.

2.Requirements

2.1.The purpose of a Design Specification is to:

a.Define the technical scope of the standard(s).

b.Define the expected use and purpose of the standard(s).

c.Define relationships with existing standards.

d.Describe the design of the standard.

2.2.Design Specification shall adhere to the format and content conventions in the attachment.

2.3.A Design Specification shall be completed prior to detailed drafting of a standard.

3.Responsibilities

3.1.Working Group Chair shall:

a.Prepare the Design Specification.

b.Coordinate the Design Specification with the SESC Management Board.

c.Coordinate the Design Specification with any Working Groups for which coordination was required in the Project Plan.

3.2.SESC Management Board shall:

  1. Decide if a Design Specification is needed, and (if so) inform the Working Group Chair of the need.
  2. Decide which items in the Annex will be required in the Design Specification, and (if one is required) inform the Working Group Chair.

c.Define coordination requirements for the Design Specification.

d.Monitor progress of Design Specification development.

Annex: Design Specification Format and Content Requirements

This annex describes the required content and format of a Design Specification. The sequence of design specification elements presented does not imply that design specifications should be developed in the order of presentation. In most instances, design specifications based on this procedure will be developed by repeated iteration and refinement of the various elements of the specification.

An overview of the structure of the Design Specification is provided by Table 1. The elements shall be ordered in the sequence of sections and subsections prescribed in Table 1. Each version of a design specification based on this procedure shall contain a title and a revision notice sufficient to uniquely identify the document. A table of contents and a list of figures shall be included in every design specification.

The Management Board is responsible for deciding if a Design Specification is necessary, and (if so) which elements are required.

4.Revision

a.This procedure shall be reviewed for changes or reaffirmation in 2001.

Table 1. SES Design Specification Format
0 Motivation for the Development of [name of standard]
1 Customers of the standard
1.1 Definition and prioritization of customers
1.2 Customer needs
2 Scope
2.1 Purpose
2.2 Field of application
3 Interaction with other standards
3.1 Vocabulary standard
3.2 Road map standard
3.3 Quality system standards
3.4 Software life cycle process standards
3.5 Supporting standards
4 Consistency among the IEEE software engineering standards standards
4.1 Style and presentation
4.2 Terminology
5 Structure of [name of standard]
6 Content of [name of standard]

The following text provides additional details regarding the required contents of each section of the Design Specification.

0 Motivation for the Development of [name of standard]

Section 0 provides a short overview of the reasons for developing the proposed standard.

1 Customers of the standard

Section 1 defines the customers of the proposed standard. See Section 4 of the SESC Master Plan for a list of customer classes and their expectations. This section is arranged in the following paragraphs.

1.1 Definition and prioritization of customers

This paragraph describes the classes of expected users. Typically, there will a principal class, a secondary class (standards writers) and one or more other classes. The priority relationship among the classes of users shall be described.

1.2 Customer needs

This paragraph describes the needs of each class of customer. The customer needs should be separated into at least the following two categories: "what" the customer needs (what is to be described) and "how" the customer needs it (how it being described). The needs in each of these broad categories may be further grouped to help understand them. For example, the "what" needs may be subdivided into concept needs, implementation needs, evaluation needs, and results needs. Also, the "how" needs may be subdivided into structure needs, terminology needs, style needs, and title needs.

2 Scope

Section 2 describes the boundary and capabilities of the proposed standard. It also describes in what situations the capabilities are intended to be used. This section is arranged in the following paragraphs.

2.1 Purpose

This paragraph describes the intended value of the proposed standard for the customers described in previous sections.

2.2 Field of application

This paragraph describes "what" will be done, i.e., the technical boundaries of the project. It may also state what is being excluded. It shall describe the category of the proposed standard (standard, recommended practice, guideline).

3 Interaction with other standards

Section 3 describes terminology, placement, and interface conventions needed to permit the IEEE software engineering standards to be recognized as integral group of professional standards. This section is arranged in the following paragraphs.

3.1 Vocabulary standard

This paragraph describes the source(s) of key terminology to be used in the proposed standard.

3.2 Road map standard

This paragraph provides the relationship of the proposed standard with IEEE software engineering standards road map. A road map provides an introduction to key software engineering concepts and guidance on the application of software engineering standards. The road map used by SESC is described in Software Engineering Standards: A User’s Road Map,James W. Moore (1997), IEEE Computer Society Press.

3.3 Quality system standards

This paragraph describes as appropriate the relationship of the proposed standard with ISO 9000 series of standards. See SESC Policy statements 1 and 4 for more information on SESC commitment to the ISO 9000 series.

3.4 Software life cycle process standards

This paragraph describes the relationship (if any) of the proposed standard with IEEE software life cycle process standards. See SESC Policy statements # 2, 5 and 6 for more information on SESC commitment to life cycle process standards.

3.5 Supporting standards

This paragraph describes the relationship of the proposed standard with other IEEE standards with which its use would interact.

4 Consistency among the IEEE software engineering standards

Section 4 describes packaging conventions needed to permit the IEEE software engineering standards have the appearance of an organized collection. This section is arranged in the following paragraphs.

4.1 Style and presentation

This paragraph provides the conventions to be followed to achieve consistency of style and presentation among the IEEE software engineering family of standards. Related standards should use a similar structure. For example, process standard that are one level of detail below an IEEE software engineering life cycle process standard should describe processes in a similar manner. Note: The style of presentation should have a logical structure that relates to normal business practice, be written in a style that can be easily understood by all personnel in the user's organization, have balanced content in each section, keep sentences short while maintaining clarity and continuity avoid dual-purpose words and idiomatic expressions.

To assist in communication and translation, easily understood graphical presentations will be used wherever possible. The use of graphical presentations should be consistent among standards.

4.2 Terminology

This paragraph provides the conventions to be followed to achieve consistency of terminology among the IEEE software engineering family of standards. Also provides is the terminology that is fundamental to the proposed standard.

5 Structure of [name of standard]

Section 5 provides the table of contents (first level) of the proposed standard.

6 Content of [name of standard]

Section 6 lists the topics to be incorporated in the proposed standard. A list of potential diagrams and relationships with the topics is provided. The topics may range from concepts to specific processes, notations, products, criteria or frameworks to be included. It also describes the method for assessing or testing the proposed standard.

Note: Sections 5 and 6 may be combined if a preliminary draft of the proposed standard is presented.

1