User's Guide Document

Preliminary Users Manual

An essential component of the SDF document is the system user manual. An initial draft of the user manual will be part of your ALPHA presentation deliverable. The user manual will be a "living" document, and you will continue to revise and enhance it during the term. At the end of the term it should be able to exist as a standalone document in electronic form, to be stored in the directory containing the SDF documentation of your system.

Final Users Manual

The final version of this document should aim to be a professional-quality document, which should be very much like reading any documentation you get with professionally produced software. For example, when you buy Quicken, you get a manual that tells you in great detail (and in language that non-computer people can understand) the following items:

How to install the software How to start the software execution How to stop the software How to uninstall the software How to use every feature and function of the software. This might be in several sections of the manual, with the simplest stuff first in its own section, and the more complicated (and advanced) functions later. Screen shots of the various windows to lead the user through the installation process and usually also the use of the software Some basic troubleshooting techniques for simple problems (This is frequently based on historical data from questions and e-mails that the company has recieved, so there is a basis for "common problems") Who to contact, and how to contact them, in case there is a real problem

These are the kinds of things that every good user's manual will contain. The intent is to provide the user with something on the order of a "software semi-expert" looking over the user's shoulder during the learning period. The more you put in (in an intelligent and intuitive manner, of course) the better the user experience will be.

Documentation Hints

• In general, if a section of a hardcopy document spans more than two pages, break it into subsections and add sub-headings. This will help the reader keep the content in a context.
• Include examples as needed to clarify the details of your project.
• If there are terms that might be unfamiliar to the reader, begin to create a glossary which defines those terms and include it as an appendix to your SDF.
• When you use acronyms in your text, spell out the entire thing at the location where it is first used, then follow that immediately with a parenthesized version of the acronym; e.g., "Three Letter Acronym (TLA)". If you have a list of acronyms included in the document, make sure to put the same information there. Once those two things are done, you can use just the acronym by itself in the remainder of the document (without the parentheses).
• Try to write the users manual with a novice user in mind. Doing so is a good compromise so that the document is not to high-level for most readers but also is not too low-level for readers who are less technically oriented.
• Don't assume that the user who reads your manual will know all about software, applications, or even running the computer; things that we as programmers feel are self-evident are often totally lost on even some experienced users.
• For example, a description of closing a window shouldn't say "close the window", it should read more like "close the window by clicking on the 'X' in the red box at the upper right-hand corner of the window."

Next Document