ICS 125: Additional Documentation
Overview
- Why Write These Documents?
- User Guide
- FAQ / Troubleshooting Guide
- Release Notes
- Installation Instructions
- Demo Script
- Implementation Documentation
Why Write These Documents?
- User documentation is an imporant part of the overall
product. It helps users get value out of the product.
- Internal documents help coordinate activity between departments
within a software company
- Filling in templates prompts/reminds you to think through
details needed to build the overall product
- This is in contrast to many of the other templates that
focused on the program part of the product)
User Guide
- Written by: Technical writing department
- Read by: Customers and End users
- Often consists of tutorial, reference, and troubleshooting
sections
- When do users actually look at the manual?
- When just starting to understand the product
- When they need to look up something that cannot be found by poking around
- When things go wrong
FAQ / Troubleshooting Guide
- Written by: Developers, Technical writers, Technical support
- Read by: Customers and End users
- Just the highlights of the user guide phrased as questions and answers
Release Notes
- Written by: Developers, Marketing
- Read by: Customers, End users
- What's New: Highlights important (to marketing) changes in this release
- Lists (almost all) changes and bug fixes
- Any other information that informs the decision to upgrade or not
Installation Instructions
- Written by: Developers, Technical writers
- Read by: End users
- Tells users how to install the product so that they can use it
- This can be very simple when installation is automated
Demo Script
- Written by: Developers, Marketing
- Read by: Sales Engineers
- In a software company, there are several people who are
constantly talking with potential customers about the product and
giving demos. They need detailed instructions on what to show.
- The demo script should highlight the product's biggest items of
value to motivate a purchase
Implementation Documentation
- Written by: Developers
- Read by: Other Developers (same company or different)
- Implementation docs help explain the implementation and how it relates to the design
- Document any tricky aspects of the implementation that future
developers would need to be aware of
- Realize that it may be you that needs this documentation if you
come back to this code 6 months from now.
- Javadocs or similar API docs are very widely used
- Also common: Detailed API or protocol specifications, developer guides, developer cookbooks
sample use cases templateexample software testing plan templateProject plan template