"How-to" Documentation

There may be any number of documents/maunals needed to explain how to get value from your software, and they may be of different forms. The specific number depends on the types of users that you have, the functions that are required, the audiences, and the format of the manuals. The requirment is that all types of users of the system, including administrators, have access to the the information that they need to run the system and gain benefit from it.

There are typically at least two different types of manuals, the user manual and the administrator manual, which are further described here. These are, however, not the only model that may exist.

There was a time when every system required a "real" manual: a paper document that users could pick up, read, and reference as needed. This is rarely the case any more. It does not mean that users don't need assistance; they now get it differently. The more graphical interfaces that we use, the less we need to describe the inputs; the more we do graphically, the more likely that we will provide the needed information on a "when needed" basis.

Given these changes, the task of writing user manuals becomes one of identifying the needs of your users and deciding how best to meet those needs. Everyone, therefore is required to produce a Documentation Plan.

The Documentation Plan

This can be a brief document that should outline who your users are. what documentation they will need, and how you will provide it for them (with an explanation of why this is appropriate). In general, this information may be provided through I am sure this list in not exhaustive and you can think of other mechanisms.

Your documentation plan will describe for me what your final system will be like, but need not contain the actual final documentation. The documentation itself will be due with the final code deliverable.

User Documentation

User documentation is a collection of information that is intended for the users of the system. If there are different types of users, there minimally must be different sections for them. The documentation needs to be written at an appropriate level for the intended audience. If the user is a reluctant computer user, the information should be very specific and avoid jargon. This is not necessary for someone who is more comfortable with computers. The skill level of the user should be defined in your user descriptions. For applications intended for younger users, think of the user documentation as the information that the teacher will need to interpret. The closer that you can get to the teacher being able to simply read the documentation to them, the more on target the writing is.

Remember that users are not very tolerant of long-winded documents. Get the essential information written up front. If there is more detail needed for special cases, put it in a separate section. Make the structure amenable to "drill-down". Of course the goal is that no one ever has to read a user manual, but you should not assume that it is that intuitively obvious! For most school-related projects, there will be two users: the student and the teacher. Do not assume that the teacher is the administrator. While in some cases this may be true, you probably need to separate the roles for documentation purposes.

Administrator Documentation

Administrator documentation is intended for the person setting up the system and managing its ongoing operation as it is used. This needs to include all software and hardware dependencies, download instructions, and any hardware set-up instructions. This is the place to document what systems have been tested, what the expected compatabilities are and any known incompatabilities. If the administrator needs to set up ids and passwords before the system is fully deployed, this needs to be covered in this manual.

The administrator documentation should include a complete set of easy-to-follow instructions of how to deploy the system in a new environment (if appropriate) or how to redeploy the system if it needs to be restarted or refreshed. You again need to be cognizant of the skill level of the administrator. You can assume that it is an adult, but given the intended audience, you must determine the appropriate level of skills that you can assume. This again should be defined in your user descriptions.