User Documentation (no quiz) Tori Bowman CSSE 375 October 8 th, 2007

Agenda State of 375 Risks User documentation

State of 375 Tomorrow: – Project work time – Risk assessment help Wednesday: – HW4 due 11:55 pm Thurs., Oct. 18 th : 1 st status report – Documentation due, Wed., Oct. 17 th – Maintenance project plan – Risk assessment

Risks If…., then… – Impact to cost and schedule Risk matrix Mitigation strategy – Plan to avoid/realize – Responsibilities – Revisit date Opportunities

References Chapter 11.5 of SW Maintenance

Definition User documentation refers to those documents containing descriptions of the functions of a system without reference to how these function are implemented Pg. 283

Constituent DocumentFunction System overviewProvides general description of system functions Installation guide Describes how to set up the system, customize it to local needs, and configure it to particular hardware and other software systems Beginner’s guide/tutorial Provides simple explanations of how to start using the system Reference guide Provides in-depth description of each system facility and how it can be used Enhancement bookletContains a summary of new features Quick reference cardServes as a factual lookup System administration Provides information on services such as networking, security, and upgrading

Other means of classification User manual – How to use the system – No details on how it does it or how to get the system to do it Operator manual – How to use the system – How to recover from faults Maintenance manual – Functional specification – Software design – High quality code listings – Test data and results

How to determine the level of documentation needed… Development methodology – Varies by organization Version of the system – Upgrades vs. new development Category of customer – ATS vs. BRS External regulations – FAA – FDA

Why do it in the first place? Facilitate program comprehension – High staff turnover – Understand rationale, functionality, other development issues – More is not always better Guide to the user – Cost of help desk vs. user’s guide Complement the system

CotD

Effective documentation (not just what’s said, but how it’s said) Writing style – Active voice – Splitting text into manageable chunks – Repeating complex explanations in different ways Document standards Quality assessment Procedures to encourage concurrent updates Good design methodologies Documentation support tools

QUESTIONS?