Typical Software Documents

1
Typical Software Documents

• with an emphasis on writing proposals

2
Technical Writing

• Will you do much professional writing?
• What type of writing does a technical person
  create?

3
Tech Documents o' Plenty

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

4
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

5
NSF Proposal Format

• Cover Sheet
• title
• dates and total amount requested
• signatures
• Project Summary
• one page max
• "intellectual merit" and "broader impact"
• Table of Contents
• Project Description
• 15 page max
• also includes results from prior support
• References Cited
• Biographical Sketches
• Budget

6
Possible Format of a Business Proposal

• Executive Summary
• Statement of Work
• Management Plan
• Corporate Qualifications
• Staffing Plan
• Pricing and Contract Requirements

7
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.

8
The Need to be Clear
9
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."

10
SOW Format example

• STATEMENT 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

11
Software Project Management Plan

• Goal Statement
• Process Model
• management and technical
• Organization
• Timetable and Deliverables
• sub-tasks
• Budget

12
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

13
System Requirements Specification

• Describes What to build, not How
• according to IEEE standard 830
• The SRS must correctly define all of the
  software requirements, but no more.
• The SRS should not describe design,
  verification, or project management details,
  except for required design constraints.

14
System Requirements Specification
15
Characteristics of a Good SRS

• Unambiguous
• Complete
• Verifiable
• Consistent
• Modifiable
• Traceable
• Prioritized

16
Ambiguousness example one

• The control total is taken from the last
  record.
• The total is taken from the record at the end of
  the file.
• The total is taken from the latest record.
• The total is taken from the previous record.

IEEE 830-1984
17
Ambiguousness example two

• All customers have the same control field.
• All customers have the same value in their
  control field.
• All control fields have the same format.
• One control field is issued for all customers.

IEEE 830-1984
18
SRS Table of Contents

• Introduction
• Purpose
• Scope
• Definitions
• References
• Overview
• General Description
• Product Perspective
• Product Functions
• User Characteristics
• General Constraints
• Assumptions and Dependencies
• Specific Requirements

IEEE 830-1984
19
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
20
SRS
21
System Design Document

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

22

• 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