User/Maintenance Manual I

Due: no later than March 8, 2001

An annotated outline of your "most read" document

General

For most teams it makes sense to produce a User Manual. For some teams there are no end users per se, but the system will need to be maintained so you will write a Maintenance Manual. What "makes sense" would be defined by what would be of most value to your client. This document will be the most read document you produce.

I am looking for a first pass at the complete document, with "stubs" for most of the content. By stubs I mean that it should contain your best guess at the actual section headings, and then some brief editorial prose describing what will eventually appear in that section. In a sense, an annotated outline of the complete document.

You should not need to delve deeper than (say) two levels of section hierarchy.

For your sake, the more complete the better. It will be virtually impossible for me to give you feedback after the final due date. I am happy to look at further revisions between now and then.

Notes on your target audience:

• User Manual: your readers are probably naive end users of the system
• Maintenance Manual: probably your Client or your Client's technical staff
• Neither manual should be identified as being submitted to your Boss--they are for public consumption

You do not need your Client's signature on either document.

Example User Manual Outline

• Cover (title page)
• Document Change History
• Table of Contents
• Introduction
  • Purpose of document
  • Targeted reader (skill level)
  • Document conventions (fonts, icons, etc.)
  • Reader Starting Points (in the manual)
• Quick Start
  • The bare minimum a person needs to get going w/ the system
• System Overview
  • High-level diagram (for example) and some accompanying prose
• Tutorial
  • One or two complete examples with actual data, actual messages, screen shots, etc.
• Reference
  • A hierarchical decomposition of your product
    • e.g., one section per input/output screen or menu, with a subsection for each button/dial/menu
    • increasing specificity at each level
  • You might follow the context model from your Contract for example. Whatever you do should make sense from the appropriate reader/user's standpoint.
• Index (if you can/want--usually non-trivial)
• Appendices
  • Quick Reference Card (could additionally cut out and laminate)
  • System Requirements
  • Installation
  • Troubleshooting
  • Maintenance Procedures and Issues
  • Contact Information (your names, Client name, current emails, etc.)

Example Maintenance Manual Outline

• Cover (title page)
• Document Change History
• Table of Contents
• Introduction
  • Purpose of document
  • Targeted reader (skill level)
  • Document conventions (fonts, icons, etc.)
  • Other relevant documents (Contract, Design, etc.)
• System Overview
  • High-level diagram (for example) and some accompanying prose
  • Directory/folder structure
  • File lists w/ locations
• Procedures
  • Editing the source
    • checking out the source code
    • editing
    • checking it back in
    • comment procedures
  • Building the system
  • Testing the system
  • Starting/re-starting the production system
  • Updating the documentation (Implementation manual, revision history, etc.)
• Index (if you can/want--usually non-trivial)
• Appendices
  • Development System Requirements (include compiler versions, etc.)
  • Example Input and Output
  • Troubleshooting
  • Contact Information (your names, Client name, current emails, etc.)
  • Client Contract (final)
  • Design Specification