Project System Documentation
810:162
Intelligent Systems
Overview
The best way to document your system is to produce two documents:
- a User's Manual, intended for use by those people who will use your
system as an application program
- a System Manual, intended for use by programmers who will install,
maintain, and modify your system and its code
For more experimental projects, you should also produce a report that
documents the process you went through in developing the syste, and
the results of some of your empirical work.
Your documents should be placed in a black binder with separate sections
for each document. Each document should have its own title page and table
of contents. The sub-sections of each document should marked for easy
access.
Some of the information in these manuals will have to be specific to the
computing environment at UNI, but wherever possible you should strive to
make your information as general as possible (that is, applicable in any
computing environment).
The User's Manual
The User's Manual will be the more frequently consulted of the two
documents and will be read by users who are not necessarily expert, even
in the environment in which your application runs. Care must be taken to
make it concise, clear, and detailed enough to be of use. You should
assume that the average reader will have little or no knowledge of
computers.
This document should contain at least six sections:
- a description of the system's purpose. This should include a
generalized description of the the system's overall functions, as
well as any commonly-encountered limitiations (such as restricted
input formats).
- the standard start-up procedure for the system. This section should
offer clear, step-by-step instructions for bringing the system
up.
- the standard shutdown procedure for the system. This section
should offer clear, step-by-step instructions for taking the
system down.
- examples of how to use the system. This section should give several
detailed examples of system runs that demonstrate a substantial
fraction of the system's capabailities. Each example should provide
screen snapshots and other support material where appropriate.
- a catalog of the system's error messages. When an error occurs
during a system run, the user should be informed through a clear
message that states what type of error has occurred and what
corrective action can be taken. This section of the User's Manual
should provide an organized catalog of these messages, along with
detailed information on the type of error and possible corrective
actions.
- a system recovery guide. Occasionally, the terminal, host computer,
or network on which the system is running will fail. This section
should direct the user to take the necessary corrective actions.
For example, what happens if the terminal is turned off due to a
power failure during data entry? Answers to these kinds of questions
will tend to be environment-specific.
The System Manual
This manual will consist of two sections:
- the operations guide, to be used by those people responsible for
operating the host machine and network.
- the programming guide, to be used by those people responsible for
maintaining (and probably modifying) the system's code.
Operations Guide
This section provides information necessary for installation of the
software.
- a description of the general hardware and software requirements
made by the system.
- a step-by-step procedure for installing the software. Any data
required by the system should be described in detail here. Also,
the section should describe what tests are to be performed in
order to assure that the software has been successfully
installed.
- a description of actions necessary for backing up the system and its
attendant data files. This should describe not only the back-up
procedure but also suggested policy for how often the system should
be backed up and for how long the copies should be kept.
- a description of actions necessary for recovering from a hardware
or software failure. If the hardware or supporting software fail,
what steps are necessary to ensure the system's integrity and to
recover the state prior to the failure? What messages should be
sent to the user?
The Programming Guide
This section gives the actual details of the software modules and data
files that comprise your system. It must be correct, complete, and
up-to-date. It should include at least the following:
- the current, team-approved structure chart for all software
modules.
- a catalog of all test data and procedures necessary for ensuring
specified functionality of the final product.
- program listings for all source code modules. Each module should
include standard file documentation (name, author, date of last
modification).
- data descriptions for files and records. For each file, this should
include name of the files, a brief description of the file's purpose
and structure, a detailed listing of the file structure, and a list
of changes to file and record structure.
Format of the Documents
These manuals must be delivered in black cardboard binder with fasteners,
as demonstrated in class. All pages must be numbered, except for the
title page and table of contents. The title page should contain the title
of the document, the names of the team members, the course name and
number, the instructor's name, the date the document is submitted, and
the department and school name. The table of contents should list all
sections and indicate the pages on which they begin. Sub-sections may
be listed if appropriate.
The sections of the document must be in the order listed above. Each
section should be marked to indicate the person(s) responsible for
writing it.
Any bibliographic references used in these documents should follow a
standard format.
Eugene Wallingford .....
wallingf@cs.uni.edu .....
January 12, 2011