Chapter 2

Analysis and Design Standards

Kris Casey Helen Lahey Aileen Cater-Steel

2.1 Analysis and Design Overview

This chapter focuses on standards for the documents developed during the analysis and design phases of the systems development life cycle (SDLC), the Software Requirements Specification and the Software Design Description.
Page 11

Information Systems Developers Handbook

The Software Requirements Specification (SRS) section outlines the characteristics of a good SRS and lists the expected deliverable contents for this document produced during the analysis phase. The section on Software Design Description (SDD) specifies the characteristics required in a good SDD and the deliverable contents required for one. The SDD is produced during the design phase. The test plan is one of the deliverable contents required in the SDD and this is discussed in more detail in the section on test plans. Software Project Management Plans (SPMP) are crucial throughout the entire project and need to be regularly updated to reflect current activities. They are initially developed during analysis phase. The standards for SPMP are presented in this chapter. Development of the user documentation is an ongoing consideration and standards relating to these manuals are outlined in the user documentation section at the end of this chapter. Computer-aided software engineering (CASE) tools automate and integrate the SDLC tasks and eliminate much of the manual effort. Where feasible, documents should be created using CASE tools according to the standards recommended in this chapter.

2.2 Software Requirements Specification

2.2.1 Characteristics of SRS

The Software Requirements Specification, which is often referred to by a number of other names, such as the Requirements Definition or the Structured System Requirement, must: correctly define all of the software requirements; exclude any design or implementation details (these will be described in the design stage of the project); and not impose additional constraints on the software.

Page 12

Chapter 2

Analysis and Design Standards

A good SRS must be written for the appropriate audience, generally the client, and must be: correct; unambiguous; complete; consistent; verifiable; modifiable; and traceable.

The SRS must address the software product, not the process of producing the software product. The IEEE Std 830-1993 Recommended Practice for Software Requirements Specifications, is recognised as the standard for this document. ISO /IEC TR 15504 1998 Information Technology Software Process Assessment (SPiCE) also provides guidance for the software requirements analysis process (ENG.1.2) and has been used as a reference in this document.

2.2.2

SRS Deliverable Contents

The Software Requirements Specification must consist of at least the following components: project objectives; project background; document purpose; system scope; functional description; user interface; and software project management plan. The actual system can be modelled using the Unified Modelling Language (UML) diagrams, a data model, a process model or a combination of these techniques. Your lecturer will specify precisely what is required in the course materials. These components will now be discussed in more detail.

Project Objectives
The objectives for the project clearly state the desired business outcomes that are expected to be achieved by the system. They can be stated in terms of improvements to the business processes and functions and what is to be done to realise these improvements.

Project Background
This brief description outlines the situation that led to the project proposal. It usually states the business conditions, problems and opportunities, from a business perspective, which contributed to the instigation of this project.

Page 13

Information Systems Developers Handbook

Document Purpose
The document purpose explains the reason for preparing the document. The primary purpose for preparing a SRS document should be to provide a complete and comprehensive description of the requirements of the proposed business system.

System Scope
The boundary of the system is defined in the system scope. The overall functions of the system should be described in general terms and the system scope must identify the inter-related components that will be included in the system and the environment that is immediately outside the system boundary.

Functional Description
The functional description briefly outlines the purpose and operation of the major or high level functions to be performed within the system. It must be supported consistently by the functional decomposition chart.

UML Analysis Diagrams

The object-oriented (OO) modelling notation has been defined in the Unified Modelling Language (UML). The Object Management Group has been set up to create standardised specifications and their web site (http://www.omg.org/uml/) provides valuable information as well as links to some UML tutorials. Your course materials also present examples of the diagramming techniques. Use Case Diagrams A use case diagram is a high level conceptual view of a system. It shows the various user roles and how those roles use the system. Use Case Scenarios A use case scenario is a sequence of steps describing an interaction between a user and a system. Each use case shown in the use case diagram will have an accompanying use case scenario which describes the steps involved in the use case. Sequence Diagrams A sequence diagram is a type of interaction diagram. It is a graphical view which emphasizes the sequence of messages among objects during a use case. Collaboration Diagrams A collaboration is another type of interaction diagram which shows the objects which collaborate together to carry out a use case and the interactions or messages that are sent between them. Analysis Class Diagram An analysis class diagram defines the components of a system. It is a model used to show the classes of objects for a system. It should contain the name, attributes and methods for each class.
Page 14

Chapter 2

Analysis and Design Standards

Data Model
A data model is the representation of the data in an organisation or business area. The data model must include an entity/attribute list and an entity relationship diagram (ERD). The ERD is a graphical representation of the entity/attribute list, therefore, consistency must exist between the ERD and the entity/attribute list. The data model documents the database design and is used by analysts to communicate with clients and with the technical team. As with many computing techniques, a data model can be represented in a number of different ways. The recommended style demonstrated here was devised by Clive Finkelstein and used in Information Engineering. The format for the entity/attribute list and the ERD symbols are defined below. An example entity/attribute list and ERD, which demonstrates their implementation, follows the format. Format for entity/attribute list ENTITY (primary key1#, primary key2#, [secondary key 1], [secondary key 2], {derived attribute 1}, {derived attribute 2}, (group attribute 1), (group attribute 2), ((repeating attribute 1)), ((repeating attribute 2)), non-key attribute 1, non-key attribute 2, foreign key 1#, foreign key 2#, ERD Symbols
Cardinality ONE ONE OR MANY

Business Rules MANDATORY OPTIONAL

The following example documents a portion of a vehicle hire system. It demonstrates principal entities (customer, vehicle), secondary entities (car, coach), type entity (vehicle type) and an intersecting entity (vehicle hire). An intersecting entity usually takes on the concatenated name of both entities. However, it is preferable to use a more meaningful name when one is available. In this example, vehicle hire is more descriptive than either customer vehicle or vehicle customer. Primary keys, compound keys, secondary keys, foreign keys and group attributes are shown in the entity list.
Page 15

Information Systems Developers Handbook

Partial entity/attribute list

CUSTOMER (customer id#, (customer name), (customer address), ) VEHICLE HIRE (customer id#, vehicle id#, hire out date, ) VEHICLE (vehicle id#, [registration no], make, model, , vehicle type#) CAR (vehicle id#, body type, no cylinders, ) COACH (vehicle id#, max no passengers, ) VEHICLE TYPE (vehicle type#, vehicle type name)

Partial ERD
CUSTOMER VEHICLE HIRE VEHICLE TYPE VEHICLE

CAR

COACH

More details about data modelling can be found in the study materials for Data Analysis and Modelling, and Advanced Systems Analysis and Design.

Process Model
Data flow diagrams (DFD) model the processes within the information system and show how the data flows through the entire system. The supporting data dictionary entries document the details of the processes, external entities, data stores and data flows. The required DFD symbols and notes in relation to these components are presented below.

Page 16

Chapter 2

Analysis and Design Standards

DFD Symbols
#

PROCESS

DATA STORE

EXTERNAL EXTERNAL ENTITY ENTITY

DATA FLOW

DFD and Data Dictionary Notes All process names and numbers, data flow names, and data store names must be consistent within the DFD and data dictionary. Meaningful and succinct names assist with comprehension. The processes must be labelled (# in above diagram) in a numeric sequence indicating the hierarchy. For example, diagram 0 processes are numbered 1, 2, 3, etc. If process 2 was exploded down to the next level, this diagram would show processes numbered 2.1, 2.2, 2.3, etc. The processes on the next level below 2.1, would be numbered 2.1.1, 2.1.2, 2.1.3, and so on. This numbering technique enables all data flow diagrams to be linked. There must be consistency with other components in the system. Document everything that is represented in the DFD in the data dictionary. Include the context diagram and all other diagrams, levelled until the processes are functional primitives, unless specific diagrams have been requested. Data flow diagrams and data dictionaries are too large and complex to be included in a meaningful way in this handbook. The textbook and unit materials for Systems Analysis and Design, and Advanced Systems Analysis and Design, provide more information and numerous examples of these components.

User Interface - Screens and Reports (First Draft)

The preliminary design of the screens and the reports is used for communication with the clients. All screen and/or report fields must be consistent with the system models (UML, data or process model). Ensure samples of management reports are provided, if applicable.
Page 17

Information Systems Developers Handbook

Software Project Management Plan

The software project management plan defines clear, discrete activities and the work needed to complete these activities. Section 2.5 provides more details on software project management plans.

2.3 Software Design Description

2.3.1 Characteristics of SDD

The Software Design Description, which is also referred to by a number of other names, such as the System Specification or the Technical Specification, is the primary medium for communicating software design information. The Software Design Description must: describe the overall software structure; identify the required software components; identify the relationship between software components; give consideration to: any required software interfaces any required security characteristic any required error handling and recovery attributes; provide format of input/output data; establish required data naming conventions; define the format of required data structures; define the data fields and purpose of each required data element; and provide the specifications for all the programs in the system.

A properly written SDD specifies the system design required to satisfy the Software Requirements Specification. A good SDD must be written for the appropriate audience, technical staff, and must be: correct; unambiguous; complete; consistent; verifiable; modifiable; and traceable.

Page 18

Chapter 2

Analysis and Design Standards

ANSI/IEEE Std 1016-1987 Recommended Practice for Software Design Descriptions is recognised as the standard for this document. ISO /IEC TR 15504 1998 Information Technology Software Process Assessment (SPiCE) also provides guidance for the software design process (ENG.1.3) and software testing process (ENG.1.6) and has been used as a reference in this section. The template for the Technical Specification used by Global Banking & Securities Transactions (GBST) has been included in Appendix A to demonstrate standards that are in use in industry. This document demonstrates that while the standards in this handbook are not exactly the same as these specialised standards, there should be no difficulty adapting to specific requirements once the need for standards is recognised. Notice the version control that is included in this sample document. This aspect of documentation is important in industry.

2.3.2

SDD Deliverable Contents

The Software Design Description must consist of at least the following components: project objectives; project background; document purpose; user interface; test plan; data conversion plan; and software project management plan. Depending on the modelling technique used, the system is defined using either UML diagrams or program specifications. These components will now be discussed in more detail.

Project Objectives
The objectives for the project are repeated from the SRS and clearly state the desired business outcomes that are expected to be achieved by the system. They can be stated in terms of improvements to the business processes and functions and what is to be done to realise these improvements.

Project Background
This brief description outlines the situation that lead to the project proposal and is normally the same as was presented in the SRS. It usually states the business conditions, problems and opportunities, from a business perspective, which contributed to the instigation of this project.

Document Purpose
The reason for preparing the SDD is explained in this section. The primary purpose for preparing a SDD document is to provide a complete and comprehensive technical design of the proposed business system.

User Interface - Screens and Reports

The detailed design for all screens and reports used by the system is required. All screen and/or report fields must be consistent with the system models (UML, data or process model).

Page 19

Information Systems Developers Handbook

UML Design Diagrams

Check the Object Management Groups web site (http://www.omg.org/uml/) for standardised techniques, diagrams and links to some UML tutorials or use the examples presented in your course materials. Use Case Diagrams The use case diagram presented in your SRS is repeated in this document to provide a high level conceptual view of the system. Design Class Diagrams Design class diagrams provide more detail and expand the analysis class diagram developed for the SRS. The attributes and methods are extended to include visibility, messages, parameters, return values and programming logic.

Program Specifications
Program specifications are used to define the functionality of each program when a data or process modelling technique is used to describe the system. Each program specification is a detailed plan for a program that will be used by the programmer to create the program code. All programs within the system, including menus and all lower level DFD processes, must be defined with a program specification. Each program specification must include program name, brief description, programming logic, references to DFD, data model, screens and reports, and any other constraints. The programming logic can be written in structured English, pseudocode, or similar.

Test Plan
A test plan nominates the test strategy, identifies the components to be tested, identifies associated test scripts/cases, sequences ordering of how testing will be executed, and identifies requirements which will be validated by tests. The schedule in the project management plan must include required resources and timeframe of the test plan. Section 2.4 provides more details on test plans.

Data Conversion Plan

A data conversion plan details how data from an existing system or new data will be captured and transformed so that it will be available to start the production cycle for the new system. The plan must identify any existing data that is to be converted, specify who will be responsible for the data conversion, and provide details of the conversion process. The schedule in the project management plan must include required resources and timeframe of the data conversion plan.

Page 20

Chapter 2

Analysis and Design Standards

Software Project Management Plan

The software project management plan defines clear, discrete activities and the processes required to complete these activities. Section 2.5 provides more details on software project management plans.

2.4 Test Plans

2.4.1 Characteristics of Test Plans

The test plan should address unit, integration and acceptance test strategies as appropriate. This plan must identify: the purpose of the test; the approach in performing the test; the components to be tested; the aggregates and sequence for testing; and associated test scripts/cases.

It is important to link the test plan back to the customers requirements that are being validated by the test. ANSI/IEEE Std 829-1983 Standard for Software Test Documentation is recognised as the standard for this document. ISO /IEC TR 15504 1998 Information Technology Software Process Assessment (SPiCE) also provides guidance for the software testing process (ENG.1.6) and system integration and testing process (ENG.1.7) and has been used as a reference in this section.

2.4.2

Test Plans Deliverable Contents

The test plans must consist of at least the following components: acceptance test strategy; software unit test strategy; system test strategy; and test cases and scripts. A brief description of these components is provided below.

Acceptance Test Strategy

The acceptance test plan must identify activities to be performed to test deliverable end-customer product. This plan must identify who is responsible the performance of the acceptance test activities (supplier or customer), and system configuration requirements for the site. It must also provide a plan validating that the delivered software satisfies the customer requirements. the for the for

Software Unit Test Strategy

The software unit test plan identifies a strategy for verifying unit functionality against the requirements and design. It also specifies how basic program
Page 21

Information Systems Developers Handbook

requirements will be verified. Additionally, it provides at a higher level a strategy for verifying software features and/or functions that operate as defined in the requirements.

System Test Strategy

The system test plan must identify a strategy for verifying the integration of system components as defined in the system specification. It must provide test coverage for all components of the system including software, hardware, external interfaces, customer documentation, installation activities and conversion programs.

Test Cases and Scripts

Test cases and scripts, which define the purpose, a set of executable test instructions, input data and the expected results, must be provided.

2.5 Software Project Management Plans

2.5.1 Characteristics of SPMP

A software project management plan (SPMP) is the controlling document for managing a software project. It defines the technical and managerial processes necessary to satisfy project requirements. This plan can be applied to any, or all segments of a software product life cycle. The SPMP specifies: tasks to be accomplished; task ownership; a concise summary of the project objectives; the product to be delivered; major work products; required resources ; schedules, milestones and target dates; and identifies the critical dependencies. ANSI/IEEE Std 1058-1987 Project Management Plans is recognised as the standard for this document. ISO /IEC TR 15504 1998 Information Technology Software Process Assessment (SPiCE) also provides guidance for the project management process (MAN.2) and has been used as a reference in this section.

2.5.2

SPMP Deliverable Contents

The recommended tools for documenting a software project management plan are Gantt and/or PERT (Program Evaluation and Review Technique) charts and work
Page 22

Chapter 2

Analysis and Design Standards

breakdown structures. Check the study materials for the specific SPMP documentation required for each course.

Gantt Chart
The Gantt chart is a graphical representation of the project that shows each task activity as a horizontal bar. The length of this bar is proportional to its time for completion. The Gantt chart must include all tasks for the project, but does not reflect the order of the tasks. It must reflect both planned and actual time for a task and must show the duration of activities. It will show the time overlap of activities and may highlight slack time available within an earliest start and latest finish duration.

PERT Chart
The PERT chart is a graphical representation of the project task activities and their inter-relationships. This chart orders the activities by connecting an activity with its predecessor and successor activities. The PERT chart must include all tasks for the project and reflect the order of the tasks. It should show any activities that can be done in parallel. The PERT chart may reflect both planned and actual time for a task, as well as show the duration of activities. It may show available slack time within activity rectangles.

Work Breakdown Structure

The project manager uses the work breakdown structure to monitor the progress of each activity associated with the project. This document also identifies the participation of individual team members in the activities. The work breakdown structure must identify the estimated start and end dates, estimated number of hours to complete, actual start and end dates, actual hours spent and hours yet to complete, and actual number of hours over/under estimation for each task and each team member.

2.6 User Documentation

2.6.1 Characteristics of User Documentation

The user documentation:

provides documentation that guides users in installing, operating and managing software;

Page 23

Information Systems Developers Handbook

provides documentation that guides users on the aspects of software maintenance that does not involve modification of the software source code; and must be suitable for its identified audience.

The user documentation may consist of one or more documents, depending on the amount of information to be presented and the needs of the audience. It will be used either to learn about the software in an instructional mode, or to refresh the memory about the software in a reference mode. ANSI/IEEE Std 1063-1987 Standard for Software User Documentation is recognised as the standard for this document. ISO /IEC TR 15504 1998 Information Technology Software Process Assessment (SPiCE) also provides guidance for the software design process (ENG.1.3) and software testing process (ENG.1.6) and has been used as a reference in this section.

2.6.2

User Documentation Deliverable Contents

A number of different types of manuals are included in user documentation. Check the study materials for the specific course to ensure that the correct user documentation is provided. Some of the documentation that is normally provided for users includes user manuals, technical reference manuals, and training manuals.

User Manual
User manuals consist of visual information about the application system, especially how it works and how to use it. These manuals provide the client with a broad picture of how to perform all the steps required for a specific task. It must be easy to follow, written to suit the proposed audience, and cover all areas of both normal and abnormal processing of an application.

Technical Reference Manual

Technical reference manuals consist of a complete list of the systems functions and commands. They must enable the reader to find answers to specific queries quickly. They are more useful for finding specific details, rather than for understanding the broader view of how a system works.

Training Manual
Training manuals are necessary for the clients when learning to use the application. The manuals need to address the major functions of the system in a manner that is interesting and easy to follow.

Page 24

Chapter 2

Analysis and Design Standards

2.7 References and Suggested Readings

Finkelstein, C. 1992, Information Engineering Strategic Systems Development, Addison-Wesley Publishing Company, Sydney. Satzinger, J.W., Jackson, R.B. & Burd, S.D. 2002, Systems Analysis and Design in a Changing World, 2nd edn, Course Technology, Cambridge, Massachusetts. Martin, J. 1990, Information Engineering, Prentice Hall, Englewood Cliffs, N.J. Shelly, G.B., Cashman, T. & Rosenblatt, H.J. 2001, Systems Analysis and Design, 4th edn, Course Technology, Cambridge, Massachusetts.

Page 25