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

2. Agenda State of 375 Risks User documentation

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

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

5. References Chapter 11.5 of SW Maintenance

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

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

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

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

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

11. CotD

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

13. QUESTIONS?