Description

The user manual is a document that explains to users (like yourselves) how to use your system. It should be written in clear prose, addressing the 'average' user; assume this person is a Rutgers DCS graduate, someone like yourself, who is interested in learning more about your DCS-ALUMS system, and what he or she can do with it. Recall that we also have users who are DCS staff who are not expected to have familiarity with Computer Science concepts -- so keep explanations in language that does not contain jargon.

The user manual document should be self-contained and self-explanatory. It should address the reader in the imperative tense (i.e., say "first do this" rather than "first you do this"). You should not assume that the user is familiar with the requirements of your system, in order to explain how to use it. Do not discuss any implementation issues, unless they affect the user's interface to the system.

It would be helpful to include a brief overview of your system's functionality followed by individual UNIX manpage-style pages for each of the major functions of the system. For example, instead of command line parameters, you might describe the menu choices on a particular page of the UI, and the consequences of each choice. Strive for brevity, but make sure your instructions are understandable. As a test, try your manual out on your friends to see if they can understand how to use your system.

We suggest the following sections in your user manual:

• Introduction: a concise statement of what your system does, including motivation for building it. Make sure to state what the reader needs to know before proceeding further.
• How to use your system -- an overall description of the style of interaction with the user
• Details of possible uses -- this section should be divided into sections of related commands; you may want to include some examples of use (e.g., common scenarios) and both a novice and expert user section.
• Error handling -- what a user can expect
• Extended example of usage -- This is a must. Show and explain what the user input is and then what the system response will be. This section can include screen shots (or you can make a short movie of a sequence of user interactions and system responses to use as a tutorial). This is an effective teaching technique and will help you start to think about how to do your project demo.
• List of known features and deficiencies.
• Acknowledgments -- In this section you explain the responsibilities of each team member with respect to this document.

When you turn in your user manual make sure to include the usual title page containing: document title (e.g., User Manual for DCS-ALUMS project), name of the team, team members who contributed to this document (including the editor), course information (i.e., CS431, Prof Barbara Ryder, Scott Selikoff- TA) and date.

Stable subproject Your stable subproject should be documented by a README file that explains (i) the functionalities included in terms of the functions described in you user manual, and (ii) how a user would install the project on the client and server side. Include any useful scripts and tests that can be used to show that the project is working. Clearly the team who tests your subproject will be performing black box tests.

Since these two deliverables are rather different, this deliverable is to handed in in 2 parts. Turn in your user manual in a file called manual.pdf for the "User Manual" assignment in handin or, alternatively, tar all the manpages together in manual.tar and turn that in. We will discuss in class on Monday how you will make accessible to other groups your stable subproject; probably you will install it on a DCS server so that the other teams can access it there. What you will turn in to the handin system under the "Stable subproject" is a description of what functionality the stable subproject supports, referencing the appropriate manpages in your turned-in documentation.

Last updated by Barbara Ryder at 2:47pm, November 26, 2006