Typical Typical Software Software DocumentsDocuments

with an emphasis on writing proposals

Technical Writing

Will you do much professional writing?

What type of writing does a technical person create?

Tech Documents o' Plenty

Project Proposal Statement of Work Software Project Management Plan System Requirements Specification System Design

Request for Proposals

RFP = Request for Proposals

most government business is done this way many companies exist solely to respond to

government RFPs

some companies also solicit work via RFPs eg addition to Thurmond Building

NSF Proposal FormatCover Sheet

titledates and total amount requestedsignatures

Project Summaryone page max"intellectual merit" and "broader impact"

Table of ContentsProject Description

15 page maxalso includes results from prior support

References CitedBiographical SketchesBudget

Possible Format of a Business Proposal

1. Executive Summary

2. Statement of Work

3. Management Plan

4. Corporate Qualifications

5. Staffing Plan

6. Pricing and Contract Requirements

Good Proposals

Be clear!!!Don't assume the reader will figure out the

details.State the obvious.

Be complete.Know what the reader wants to know and

provide that information.

The Need to be Clear

Statement of Work

The usual written agreement before any work has started or any contract has been signed. Usually created by the software company. Always fairly short.

"A SOW should specify in clear, understandable terms the work to be done in developing or producing the goods to be delivered or services to be performed by a contractor.

A SOW defines (either directly or by reference to other documents) all non-specification requirements for contractor effort."

SOW Format – exampleSTATEMENT OF WORK

1. GENERAL. The Bureau of Reclamation has a requirement for …

2. BACKGROUND.

3. WORK TO BE PERFORMED BY CONTRACTOR.

4. GOVERNMENT-FURNISHED MATERIALS/SERVICES.

5. SUMMARY OF DELIVERABLE.

6. PROJECT COMPLETION/DELIVERY SCHEDULE

6.1 REVIEW OF DELIVERABLES.

6.2 ACCEPTANCE OF DELIVERABLES.

7. CONTRACTOR PAYMENT SCHEDULE

8. TECHNICAL COORDINATION

9. ADDRESS FOR DELIVERABLES

Software Project Management Plan

Goal Statement Process Model

management and technical

Organization Timetable and Deliverables

sub-tasks

Budget

IEEE 1058 Standard for SPMP

1. Introduction 1.1 Project overview 1.2 Project deliverables 1.3 Evolution of the SPMP 1.4 Reference materials 1.5 Definitions and acronyms

2. Project organization 2.1 Process model 2.2 Organizational structure 2.3 Organizational boundaries and interfaces 2.4 Project responsibilities

3. Managerial process 3.1 Managerial objectives & priorities 3.2 Assumptions, dependencies & constraints 3.3 Risk management 3.4 Monitoring & controlling mechanisms 3.5 Staffing plan

4. Technical process 4.1 Methods, tools & techniques 4.2 Software documentation 4.3 Project support functions

5. Work packages, schedule & budget 5.1 Work packages 5.2 Dependencies 5.3 Resource requirements 5.4 Budget & resource allocation 5.5 Schedule

System Requirements Specification

Describes What to build, not How

according to IEEE standard 830:

1. “The SRS must correctly define all of the software requirements, but no more.”

2. “The SRS should not describe design, verification, or project management details, except for required design constraints.”

System Requirements Specification

Characteristics of a Good SRS

1. Unambiguous

2. Complete

3. Verifiable

4. Consistent

5. Modifiable

6. Traceable

7. Prioritized

Ambiguousness – example one

The control total is taken from the last record.

1. The total is taken from the record at the end of the file.

2. The total is taken from the latest record.

3. The total is taken from the previous record.

IEEE 830-1984

Ambiguousness – example two

All customers have the same control field.

1. All customers have the same value in their control field.

2. All control fields have the same format.

3. One control field is issued for all customers.

IEEE 830-1984

SRS Table of Contents1. Introduction

1. Purpose2. Scope3. Definitions4. References5. Overview

2. General Description1. Product Perspective2. Product Functions3. User Characteristics4. General Constraints5. Assumptions and Dependencies

3. Specific RequirementsIEEE 830-1984

3. Specific Requirements 3.1 Functional Requirements 3.1.1 Func Req 1 3.1.1.1 Introduction 3.1.1.2 Inputs 3.1.1.3 Processing 3.1.1.4 Outputs 3.1.2 Func Req 2 … 3.2 External Interface Requirements 3.2.1 User Interface 3.2.2 Hardware Interfaces 3.2.3 Software Interfaces 3.2.4 Communication Interfaces 3.3 Performance Requirements 3.4 Design Constraints 3.4.1 Standards Compliance 3.4.2 Hardware Limitations 3.5 Attributes 3.5.1 Security 3.5.2 Maintainability 3.6 Other Requirements 3.6.1 Database

IEEE 830-1984

SRS…

System Design Document

Data Dictionary Entity Relationship Diagrams Data Flow Diagrams Control Flow Diagrams Use Case Diagrams State Transition Diagrams

Proposal we would like to do this for this amount

Statement of Work we agree to do these things for this amount

Software Project Management Plan who is doing what, when, and how

System Requirements Specification what must this software do, contain, etc

Software Design how is this software put together