A HANDBOOK FOR SOFTWARE DEVELOPMENT

Home

PROCEDURES FOR
SOFTWARE DEVELOPMENT

These procedures are intended for small software development projects. Take them and adapt to your own needs.

CONTENTS

General rules
Document standard for Software Requirements Specification
Document standard for Software Test Specification
Document standard for Software Design Description
Document standard for Software Development Plan
Procedure for System Test
Procedure for Reviewing
Procedure for Milestone Passing
Procedure for Document Control
Procedure for Project Management

------------------------Top-----------------------

GENERAL RULES

1. GENERAL

Development of software shall be conducted in four consecutive phases: Requirements Analysis, Design, Unit Design, and System Test. Each phase ends with a milestone. A phase may not start until the preceding phase is finished. A phase is finished when the milestone at the end is passed by formal approval.

The results of the phases shall be, respectively:

Requirements Analysis	Software Requirements Specification (SRS)
Design	Software Test Specification (STS) Software Design Description (SDD)
Unit Design	Source Program
System Test	Tested and corrected source programs Corrected SRS, STS, and SDD Possibly user documentation

Software Requirements Specification, Software Design Document, Software Test Specification, and Source programs, shall be reviewed before approval.

Deviations from this set of procedures shall be documented in the SDP of the project.

In this set of procedures, the word "document" also includes source programs.

2. RULES FOR WRITING

Lack of information in a document is a fault.

Unnecessary information in a document is a fault.

All headings from the document standards shall be included in the documents prepared, with the following execption: If no text is needed under a certain heading, the text "Not applicable" is put there, and possible sub-headings are excluded.

------------------------Top-----------------------

DOCUMENT STANDARD FOR SOFTWARE REQUIREMENTS SPECIFICATION

1. GENERAL

Identify the software system specified by the requirements specification.

Give an overview of this software system.

2. REFERENCES

List all documents referred to in the text, plus any further documents needed by the reader in order to understand the specification.

3. DEFINITIONS

Explain all abbreviations.

Define all concepts which are not self-obvious for all groups of readers.

4. TECHNICAL REQUIREMENTS

All external requirements on the properties of the software.

4.1 External interfaces

4.2 Functional requirements

4.3 Dependencies between functions

4.4 Requirements regarding operation
- Adaptation for each installation
- Restart
- Installation
- Etc.

4.5 Capacity requirements
Requirements regarding capacity, performance, and capacity utilization

4.6 Security requirements
Requirements regarding e.g. the system's
- Protection of data
- Security against intrusion

4.7 Safety requirements
Requirements on the system regarding e.g. safety against personal injury

4.8 Design requirements
Requirements regarding the design of the software, e.g.
- Programming language
- Operating system
- Incorporation of existing software modules

4.9 The user's capacity and competence
To be formulated as requirements on the software system.

4.10 Other requirements

5. SUPPLEMENTARY INFORMATION

CHECKLIST FOR REVIEW OF A REQUIREMENTS SPECIFICATION

Is the software uniquely identified?
Are any requirements missing?
Are all requirements necessary?
Are there contradicting requirements?
Is everything formulated clearly and unambigously?
Is any requirement described in too much detail?
Is any requirement described too vaguely?
Will the customer understand the requirements specification?
Can all requirements be tested?
Is the word "shall" used to indicate requirement?
Is there unnecessary text or unnecessary pictures?
Are all requirements on external interfaces specified?
Are the requirements on all functionality specified?

------------------------Top-----------------------

DOCUMENT STANDARD FOR TEST SPECIFICATION

1. GENERAL

Identify the software system specified by the test specification.

Give an overview of this software system.

Specify what requirements specification (including version) the test is intended to verify against.

2. REFERENCES

List all documents referred to in the text, plus any further documents needed by the reader in order to understand the specification.

3. DEFINITIONS

Explain all abbreviations.

Define all concepts which are not self-obvious for all groups of readers.

4. TEST ENVIRONMENT

Identify all equipment needed for the test.

4.1 Software

4.2 Hardware

5. PREPARATIONS

Specify what needs to be done before starting executing the test cases.

6. TEST REQUIREMENTS

6.1 General test requirements
All requirements on the behaviour of the software, not pertaining to a specific test case.

6.2 Test case 1
6.2.1 Goals
Requirement or "accident" to be tested.

6.2.2 Initialization

6.2.3 Assumptions and constraints

6.2.4 Criteria for approval

6.2.5 Test steps
Describe the test steps in turn. The test steps to be numbered consecutively.

6.3 Test case 2
...

7. SUPPLEMENTARY INFORMATION

CHECKLIST FOR REVIEW OF A TEST SPECIFICATION

Is the test object unambigously identified?
Is it clear what requirements specification is concerned?
Is the correct version of the requirements specification referred?
Are all necessary definitions included?
Is the test environment unambiigously identified?
Is something missing in the description of the test environment?
Are the preparations clearly described?
Are the preparations sufficient?
Will all requirements be sufficiently tested?
Is it clear how the general test requirements are to be met?
Are implied requirements covered?
Are there unnecessary test cases?
Are there unnecessary test steps?
Are there unnecessary text or unnecessary pictures in the test specification?
Are all test cases specified on a suitable level of detail?
Are the criteria for approved test cases and test steps clear?
Does the test specification follow the template?

------------------------Top-----------------------

DOCUMENTATION STANDARD FOR SOFTWARE DESIGN DOCUMENT

1. GENERAL

Identify the software system specified by the design specification.

Give an overview of this software system.

Specify what requirements specification (including version) the design specification is to meet.

2. REFERENCES

List all documents referred to in the text, plus any further documents needed by the reader in order to understand the specification.

3. DEFINITIONS

Explain all abbreviations.

Define all concepts which are not self-obvious for all groups of readers.

4. OVERALL DESIGN

4.1 System environment
Overview of the software system in its environment.

4.2 System architecture
Overview

4.3 States

Description of the different states of the software, in order to simplify for the reader to understand the design.

4.4 Capacity budget
Assignment of capacity (processor time, memory) to the software units. Only don when needed.

4.5 Principles for failure handling

Handling of failures outside the software. Error messages.

4.6 Global data

Data and data types accessible to more than one software unit.

4.7 Stored data

Data on disk.

5. PROGRAM UNITS

5.1 Program unit 1

5.1.1 General

5.1.2 External interface unit 1

5.1.3 Functionality unit 1

5.2 Programenhet 2

5.2 Program unit 2
...

6. SOURCE PROGRAM FILES

Identify the source files which will make up the software system. Specify their contents.

7. SUPPLEMENTARY INFORMATION

CHECKLIST FOR REVIEW OF A SOFTWARE DESIGN DOCUMENT

Is the software unambigously identified?
Is there specified what requirements specification to meet?
Is the correct version of the requirements specification referred?
Does the design document cater for all requirements?
Are there functionality or interfacew, which are not required by the requirements specification?
Check that any requirements in the test specification have been met.
Is the description of external interfaces correct?
Is the principle for error handling good?
Is the overview diesciptions in paragraphs 4.1-4.3 good?
Are there any multiple descriptions of the same interfaces between program units?
Will the program units be of right size and complexity?
Is the structure of program units easy to understand?
Is the design easy to modify?
Are all program units sufficiently described?
Is there unnecessary text or unnecessary pictures in the design document?
Is a capacity budget needed in the design document?
Does the design document follow the template?

------------------------Top-----------------------

DOCUMENT STANDARD
FOR SOFTWARE DEVELOPMENT PLAN

1. MISSION

Identification of the product to be created by the project.

Identify the "sponsor", i.e. who controls project goals and budget.

2. REFERENCES

A list of all documents or parts of documents referenced in the plan.

3. DEFINITIONS

Explanations of all special terms and concepts used in the plan.

4. PROJECT MANAGEMENT

4.1 The organization and resources of the project

Description of the project organization. At least document what persons fullfil these functions:
- Project leader
- Project librarian
- Developer(s)
- Review chairperson(s)
- Tester(s)

4.2 Time schedule and cost plan

This paragraph shall include a Gantt diagram with all planned activities. The diagram shall contain estimated work amount for each activity, and milestones shall be clearly marked.

In this paragraph, also work estimates for activities outside the schedule shall be documented, as well as expected costs for such activities.

4.3 Descriptions of activities

Here shall be described for each activity, what is meant, and the criteria for viewing the activity as finished.

4.4 Progress reporting

Method, interval, and receivers for progress reports.

4.5 Dependencies

Describe external dependencies which could influence the project, e.e. dependence of work results from other projects. Describe how to handle these dependencies.

5. SOFTWARE DEVELOPMENT

5.1 Standards and procedures

References to all standards and procedures, which control the software development.

5.2 Existing software

Reference to existing software, which is to be reused.
- Identity
- Handling of changes
- Handling of licenses
- Handling of master media, e.g. CD disks.

5.3 Development environment

Any decisions about what development tools (e.g. compilers) to use, and their version.

6. CHECKING OF WORK RESULTS

What reviews, tests, and milestone passages are to be conducted, and the manner for them. How many persons to be involved in reviews, and possibly their names.

7. DOCUMENT CONTROL

Define how documents are to be approved and recieve identities.

Describe or reference prodedure for change control.

8. DELIVERY AND PROJECT CONCLUSION

What will be delivered, in what form, and where.

What are the criteria for the project to be finished?

9. QUALITY GOALS

Any specific goals regarding quality. For example, a maximum number of errors to be found during the first year of use.

------------------------Top-----------------------

PROCEDURE FOR SYSTEM TEST

1. GENERAL

1.1 Goal

The goal of System Test is to demonstrate that the developed software meets

The requirements in the software requirements specification
Obvoius, implicit requirements

The goal is to be met through the conduct of the system test in accordance with the appropriate test specification.

1.2 Finishing criteria

The system test is finished when all test cases have been run through on the same software with correct result, i.e. when any errors have been corrected and tested.

The tester shall attest this by his/her signature on the first page of the test report.

2. RESULTS

The result of the system test is a test report, consisting of a copy of the test specification, information about any error reports raised, and information about program versions tested.

A copy of the current test specification with handwritten notes shall be part of the test report. The following shall be noted in the test report:

The text "Test Report" on the first page.
Date and the tester's signature in the margin for each successful test case.
The statement "The whole test has been performed with correct result" followed by the date and the tester's signature on the first page.
If all test cases have not been run on the same software version, the tester shall note for all test cases what software version was used when the test case was run successfully.

The project leader shall archive the test report.

3. PROCEDURE

Before starting the system test, the tester shall check that the right test environment and the test equipment are available.

The tester shall compile and link the software system to be tested, and give an informal version number to it, e.g. T1. He/she shall make a note of identity and version for all program units included.

The tester shall perform all preparations and go through all test cases in accordance with the test specification.

The tester shall write error reports on all errors found.

After an error has been corrected, the tester shall execute the test case where the error was found, plus any further retesting decided during handling the error report.

If an error is found in the test equipment, the tester is allowed to correct it him-/herself and approve the correction in the error report.

When a test case has been executed with correct result, the tester shall note this with date and signature in the test specification.

Whan all test cases have been executed with correct result, the tester shall write in the first page of the test specification "The whole test executed with correct result" followed by date and the tester's signature.

------------------------Top-----------------------

PROCEDURE FOR REVIEWING

1. SCOPE

This procedure covers internal reviews of documents within a development project.

All product documents shall be subject to review before approval. Product documents are:

Software Requirements Specification
Test Specification
Design Document
Source code file

2. THE PROJECT LEADER'S TASKS

The project leader shall

plan reviews
assign reviewers and review leaders
check that the reviews are effective
when needed, ask for permission to omit a review, when it is not necessary.

3. THE REVIEW LEADER'S TASKS

The review leader decides the time for the review meeting.

During the review meeting, the review leader shall

check that the reviewers are sufficiently well prepared
keep the minutes
be chairman
make the review decision, if the reviewers can not agree about it
if needed decide that someone else shall check the author's corrections
distribute review minutes
see to it that "other issues" are relayed to concerned persons, and thereafter sign them in the minutes.

When required by the review decision, the review leader (or some other assigned person) shall review and approve the author's changes after the meeting. This person shall approve the correction for each review remark in the review minutes. When all remarks have been corrected or shown to be unwarranted, the review leader shall increase the version number of the review minutes, and distribute them again.

4. THE REVIEWER'S TASKS

Before the review meeting, the reviewer shall review the document or program (or assigned part of) with a critical eye to find as many possible errors and obscurities as possible

During the review meeting, the reviewer shall present his/her finding. The reviewer shall participate in the discussion and help the meeting to decide which of his/hers own and other's findings actually have to be attended to. During the meeting, the reviewer shall look for further errors and obscurities, and bring them up.

After the meeting, the reviewer shall when needed help the review leader (or some other assigned person) to judge the modifications made by the author.

After the review meeting, the reviewer shall be prepared to discuss review remarks with the author and suggest corrections.

5. THE AUTHOR'S TASKS

The author shall inform the review leader when the document is ready for review.

The author distributes the review object, any other material, and the call for meeting to the reviewers.

For each review remark, the author shall after the meeting either change in the document, or show that the remark is unwarranted.

6. REVIEW REPORT

Review reports shall be prepared using the forms shown below.

The project leader shall keep the report during the lifetime of the project, and afterwards offer it to the quality department of the company.

Date:	Release:	Page: 1
REVIEW REPORT
Project:	Review object:
Review no.:	Review meeting date:
Author:
Review leader:
Reviewers:
.
.
.
.
CC:
.
.
Decision [ ] The document is approved [ ] Document to be reviewed anew [ ] Changes to be reviewed by:
Review leader's signature:
The document is approved (sign.):
Milestone approval	Date:	Milestone no.:
Manager sign.:
Customer sign. (if needed):

Date		Version:		Page:

REVIEW OBSERVATIONS
Review object:

No.	Review observation	Not changed	Approved
No.	Review observation	Not changed	Date	Sign
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.
.	.	.	.	.

Date:		Version:		Page:

OTHER ISSUES
Review object:

No.	Remark		Approved
			Date	Sign
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.
.	.		.	.

------------------------Top-----------------------

PROCEDURE FOR MILESTONE PASSING

1. GENERAL

This procedure covers milestones within a software development project.

"Client" is the line manager, th whom the project leader reports.

Each phase in the project shall end with a milestone.

A milestone is passed when the project leader has presented the required results and information for the client, who has approved the milestone.

In some cases, the contract with the customer requires opportunity for a representative for the customer to take part in milestone passings. In such cases, the representative can approve the milestone through a signature onthe same document, where the client signs his approval. The client's approval is what constitutes approval to continue the project. If the customer's representative has an other opinion, this is brought up in other fora.

2. MILESTONE 1

Milestone 1 finishes the phase "requirements analysis". Participants are project leader and client (responsible manager).

The project leader presents the report(s) from review of the requirements specification and the approved requirements specification to the client.

The client checks that all review observations have been acted upon. The client approves the milestone by signing the (last) review report by the field "Milestone approval".

Possibly, a representative for the customer also approves the milestone through a signature by the same field.

The review report with the milestone approval is archieved within the project in the same way as other review reports.

3. MILESTONE 2

Milestone 2 finishes the phase "design".

The project leader presents the reports from review of the test specification and the design document, as well as the approved documents for the client.

The client checks that all review observations have been acted upon. he also checks that any design requirements in the test specification are met. The client approves the milestone by signing the (latest) review report for each document by the field "Milestone approval".

Possibly, a representative for the customer also approves the milestone through a signature by the same field.

4. MILESTONE 3

Milestone 3 ends the phase "unit design" and is an assurance that the system test can start.

The project leader presents the following for the client and possibly a representative for the customer:

Review reports for all program units
Documentation of the integration
A list of all equipment needed for system test
A list of the contents of the project library, including version numbers
A list of all open error reports and change requests.

The client checks that all program units are reviewed, approved and integrated, and that all test programs and other equipment needed for system test are available.

The client checks that all documents in the project library are approved and in the latest version.

The client checks that for all open error reports thera are an approval from the customer that the software may be delivered without correction of these.

The clients checks the same regarding all open change requests raised by the customer.

Further, the project leader demonstrates that all required changes of requirements specification, test specification, design document, and source programs, have been taken care of.

The client writes "Milestone 3 approved" and date on the list of the contents of the project library, and signs it.

Possibly, also a representative for the customer signs the same document.

The signed list is kept by the project leader, and at the end of the project, he/she offers it to the company's quality department for archieving.

5. MILESTONE 4

Milestone 4 ends the phase system test, and indicates that the client accepts the results of the project.

At milestone 4, the project leader is to present the following:

Documentation of the system test
A list of all error reports raised after milestone 3
A list of all documents and programs included in the delivery from the project. This list shall give version numbers.

The client shall check the following:

that the system test is completely finished
for every error report since milestone 3 that the error has been corrected, or that the customer has accepted that it does not need to be corrected in this version of the product.
that the list of project deliverables is in agreement with the assignment, and that everything included in the delivery is approved.

On the list of the contents in the project delivery, the client shall write "Milestone 4 approved" and date. He/she then signs the list to indicate approval. The project leader keeps a copy of the signed list, and offers the original to the quality department for archieving.

The customer approves milestone 4 only when the system test is used as a part of the customers acceptance of the software system. If there is no other requirement on the form of the approval, a representative for the customer may approve the milestone by a signature on the same document where the client approved the milestone.

------------------------Top-----------------------

PROCEDURE FOR DOCUMENT CONTROL

1. GENERAL

1.1 Scope

This procedure covers approval, archiving and change control, within a project, of product documents and software development plan.

1.2 Types of documents

The following types of documents are product documents:

Software requirements specification
Software test specification
Software design document
Source program files

Product documents must be maintained during the whole life-time of the product.

The following types of documents are project documents:

Software development plan
Review records
Test records
Milestone records

Project documents must be maintained during the life-time of the project. At project conclusion, they shall be offered to the company's quality management for archieving.

2. DOCUMENT APPROVAL

Software development plan shall be approved by the person ordering the project.

Software requirements specification, software test specification, software design document, and source programs shall be approved by the project leader.

Paper documents are approved through a signature on the original.

The first version of a computer stored document is approved through a signature on the review record.

Later versions of computer stored documents are approved through signatures on the change requests which define the difference between the new version and the previous one.

3. INSTRUCTION FOR PROJECT LIBRARIAN

The librarian is responsible for an archive for computer stored originals, and if needed for paper originals. Originals of obsolete versions shall be kept in the library.

Computer stored originals shall be protected so that they can be copied and replaced only by the project librarian and by the project leader.

The librarian shall keep a list of the document originals in the library. The list shall include:

document identity
version number
date when entered into the library

The librarian shall keep a list of the documents which are logged out for change.

When presented with evidence of approval, the librarian shall insert originals of new versions into the library.

When presented with an approved change proposal, the librarian shall surrender document copies for modification, if they are not alreade logged out for change.

When the librarian inserts a new original, (s)he shall distribute copies to all project members. When the software development plan is inserted, a copy shall also be distributet to responsible manager and possibly to the customer.

4. DOCUMENT CHANGES

4.1 The change form

Document changes shall be documented in the change form found below.

If there is too little room for text in the form, separate papers can be stapled to the form.

Cange forms with serial numbers shall be available in a binder, to which all project members have access. Forms, which are fully or partly filled in, shall be kept in original or copy in a binder for used forms.

4.2 Error report

Who finds an error, fills in the first part of the form "Error report" with a description of the error, date and signature. Then (s)he inserts a copy of the form into the binder for used forms.

In the part "Error report", the project manager shall document his/her decision. Alternatives are:

"To be corrected"
"Resting"
"No action"

If the decision is not to act on the report, the original is inserted in the binder for used forms, and in the list over used forms, the decision is noted ("resting" or "no action").

4.3 Change

Changes are requested by filling in the part "Change proposal" in a change form. If a change request is initiated without any error reported, the part "Error report" does not have to be filled in.

The project leader approves the change proposal and give it to one or more developers to implement in the affected documents. If several changes are to be done in the same document, one developer gets them all.

The developer logs out the document from the librarian, inserts the changes, and give a new version number to the document.

After the project leader approving the change in the form, the developer gives the document to the librarian for archiving and distribution.

CHANGE FORM											Number:
.
Error report								Date:		Signature:
.
Description:
.
.
.
.
.
Decision:							Date:		Signature:
.
Change proposal				Date:		Signature:
.
Description:
.
.
.
.
.
Approved			Date:		Signature:
.
Change approval (approval of new versions) .

Document no:		New version:
Document no:		New version:
Date		Signature:
.
Customer approval (if needed)
Date:	Signature:

------------------------Top-----------------------

PROCEDURE FOR PROJECT MANAGEMENT

1. GENERAL

This instruction gives tasks, responsibility and authority for a project leader of a software development project.

Every project leader shall have assigned a "sponsor" or internal customer. Normally, this is the person who controls the money and other resources committed to the project.

2. PLANNING

The project leader shall prepare a Software Development Plan (SDP) in accordance with the document standard. The SDP shall be updated when needed.

The sponsor shall review and approve all issues of the SDP.

3. REPORTING

The project leader reports to the sponsor.

The project leader shall on a regular basis prepare in writing a progress report for the sponsor. The report shall at least include

Accumulated costs
Passed milestones
Finished activities., meaning such activities which are included in the time schedule.
Resolved problems.
Existing problems. Intended solutions.
Potential problems.
Current time schedule and cost plan. Is only needed when the project leader's current estimates differ from the time schedule and cost estimates in the Software Development Plan.

The project leader has the obligation to inform the sponsor immediately if (s)he suspects that the project will exceed the time or cost estimates.

4. CHANGES WITH IMPACT ON THE CUSTOMER OR ANOTHER PROJECT

For each required change and reported problem, the project leader shall determine whether the change or the problem has impact on the customers requirements or on some other project. In such cases, the project leader shall acquire acceptance for the change or the action. This acceptance shall be in writing.

5. MANAGING THE PROJECT

Within the limits of the Software Development Plan, the project leader controls and directs the work in the project. Within the project budget, the project leader decides expenses.

------------------------Top-----------------------