Documentation Standards

1
Documentation Standards

• CS4320
• Fall 2002

2
Presentations

• Start on Wednesday
• Each student 15 minutes
• You are covering material for whole class
• Send me your slides if you want on web
• Material is testable
• Attendance is mandatory

3
Contracting Digression

• Competition
• Some RFPs
• http//www.smdc.army.mil/Contracts/archive/CBDpres
  ol.html
• http//cbdnet.access.gpo.gov/frame-test-01a.html
• Responding by writing a proposal
• Cost
• Technical Approach
• Proposal evaluated by Source Selection Board
• Decision on best value vice lowest bidder
• Usually split 60-40 Tech Merit and Cost
• Always read RFP carefully!

4
Proposal Contents

• Technical Description (our understanding of the
  problem, our experience and tools in this area)
• Assumptions
• Proposed Solution (our specific solution based on
  tech desc)
• Effort Estimate
• Project Schedule
• Customer Responsibility
• Penalty/Reward for timely delivery
• Risk management
• Requirements Changes (How are these done?)
• Other requirements and issues (Security,
  Management)
• Resumes of key people

5
OO Design Digression

• Open Closed Principle
• Modules are open for extension, closed for
  modfication.
• Liskov Substitution Principle
• Subclasses should be substitutable for their base
  classes.
• Consider behavior, not just is a
• Square/rectangle problem
• Dependency Inversion Principle
• Depend upon abstractions, not concretions

6
More Design Digression

• Interface Segregation Principle
• Many client-specific interfaces are better that a
  single general-purpose interface
• Release-Reuse Equivalency Principle
• The granule of reuse is the granule of release.
• Common Closure Principle
• Classes that change together belong together
• Common Reuse Principle
• Classes that are not reused together do not
  belong together.

7
Still more design digression

• Acyclic Dependency Principle
• The dependencies between packages must not form
  cycles.
• Stable Dependency Principle
• Depend in the direction of stability
• Ca incoming dependencies
• Ce outgoing dependencies
• Instability (I) Ce / (Ca Ce)
• Depend on packages whose I metric is lt you

8
Yet more design digression

• Stable Abstractions Principle
• Stable packages should be abstract packages
• Nc number of classes in a package
• Na number of abstract classes in package
• Abstractness (A) Na / Nc
• Distance A I -1

9
Documentation Types

• Process Documentation
• Plans, estimates, schedules
• Reports
• Standards
• Working papers
• Memos/email

10
Documentation Types

• Product Documentation
• User Manuals (administration, reference, install,
  tutorials)
• System
• Requirements Document and Specification
• Architectural Description
• Component Descriptions
• Source code listings
• Validation documents
• Maintenance guide

11
Why are we wasting time on this?

• Large amounts of documentation are generated.
• Documentation is often a delivery item on
  contract.
• Overall quality of documentation is poor.
• Documentation quality affects overall quality.

12
Some tips

• Active vice Passive
• Check ur grammur and spellin
• Short and single topic sentences
• Short paragraphs
• Concise (to be verbose can sometimesbut not
  alwayscause understanding and comprehension
  problems amongst some categories of users and/or
  potential administrators of the system or systems
  under development.)
• Be precise define terms
• Repeat complex descriptions
• Use headings
• Itemize facts
• Do not refer to references alone.

13
IEEE Std 1063-2001

• Minimal components of user documentation
• Identification data
• Table of Contents
• List of Illustrations
• Introduction
• Information on use of document
• Concept of operations
• Procedures
• Information on SW commands
• Error messages and problem resolution
• Glossary
• Navigational features
• Index (if gt 40 pages)
• Searchable (if in electronic format)

14
Dont forget

• Peer Reviews
• ADA
• Allowing time for publishing cycle
• Beware electronic media for all manuals

15
Next Time

• Other Process Improvement Frameworks
• SPICE
• ISO 9000
• Bootstrap