Project 1 Deliverables
CIS 422 Spring 1998

In the Project 1 description, the last task in week 4 is: On Friday you declare victory and turn in your project by e-mailing the instructor and teaching assistant a URL at which the whole thing can be downloaded. This document describes in more detail what you will turn in, and how you will turn it in.

What's in a Product?

Your product should include at least the following:

User manuals

Provide documentation to help the user install, use, and trouble-shoot the software. Ideally this would consist of at least three different documents: Installation instructions, a tutorial, and a reference manual. You may not have time to produce three different documents, but you should be sure to address all of these needs. Good installation documentation will be especially important if the user is required to download some auxillary software, such as a graph-layout program that cannot be legally included in your distribution package.

README

The README file should identify the product and version, and should at least provide a short guide to finding information in the other documentation. Some essential information should be provided directly in the README file, even if it repeats information provided elsewhere. Among the essential information is: What are the installation requirements for this software? Does it require a particular platform (e.g., Unix)? Does it require any other resources? Who produced the software? To whom should one send bug reports, suggestions, and requests for more information?

Developer/Maintainer documentation

Documentation for developers and maintainers is not always "in the box," but it is no less a part of the product when it is kept in the developing organization. In the spirit of freeware, your technical documentation should be part of the package that is provided to users. A technically adept user should be able to use your documentation to determine how to extend or modify your product.

Full Source

Source for everything. That includes programming language source code, of course, but also other kinds of source. For example, if you distribute your user manuals as html or pdf, but compose them in a word processor, the word processor files are "source" and the html or pdf files are "object code."

The Program(s)

This is the only optional item. You may prefer to make generation of the program(s) part of installation (e.g., if the system is portable to different hardware platforms).

More about Manuals

Surely all of you have written programs before, but you may be less familiar with user documentation. A thorough discussion of user manuals doesn't fit here, but here are a few pointers to keep in mind.

Tutorial documentation is generally task-oriented, and each task description is intended to be read sequentially. Usually it is arranged starting from descriptions of simple tasks that every user will perform, followed by more complex and specialized tasks. Reference manuals are "random access" documents. They are not intended to be read sequentially, from front to back. It should be easy to find a specific piece of information in a reference manual quickly. Unless the document is very short, a table of contents and an index are essential.

It is possible to write a single document that serves as both tutorial and reference, but it is important to keep these two different ways of using a manual in mind. Can a new user pick it up and, after only a brief reading, start to perform useful tasks? Can a new or old user quickly locate some particular detail? The dot manual included with AT&T''s Graph_Viz package is a good example of a short manual that manages to serve both uses. At the other extreme, Adobe's series of PostScript manuals (Tutorial and Cookbook, Language Reference Manual, and Program Design Guidelines) are a nice example of specializing different manuals for these different uses.

Don't take the task of writing manuals too lightly. They are important to the usability of your product. Don't think that, because your audience is webmasters, they don't need good documentation --- they may just need different documentation than novice computer users. I will not prescribe a minimum required size for the documentation, but I do want to be very clear that this is not something you can throw together at the last minute.

Packaging the Product

Your product should be downloadable from a web page. It must be downloadable as a single file. You may use any of the following formats:

Gzipped tar (.tgz) file:

All the parts of your product are collected in a single Unix tar file and then compressed with the Gnu zip utility. This is an appropriate way to distribute products that are intended to be used (only) in a Unix environment.

Zip (.zip) archive:

All the parts of your product are collected in a single zip archive. This is an appropriate way to distribute products that are intended for use (only) in a Windows environment.

The web page from which your product is downloadable should contain much of the information in your product concept document. It should tell: What does your product do? Who is it for? What is needed to install and use it? How can a user obtain more information? It is the URL of this web page that you will email to sahrk@cs.uoregon.edu and michal@cs.uoregon.edu by Friday at 5pm.

What About Grading?

We will grade the version of the product that we download Friday evening. At least the following factors will be considered in the overall evaluation:

• Dependability: Does the product do what it claims to do?
• Usefulness: Does it serve its purpose well? Does it have an appropriate set of features? To what extent is this a product that will be useful to its intended target users?
• Usability: Is the product easy to learn and efficient to use? Note that user interface, documentation, and feature set all play a part in overall usability.
• Limitations: What are the limitations of the product? Are any of them likely to interfere with its usefulness to its intended audience?
• Maintainability and extensibility: To what extend does the design and its documentation enable other developers to modify and extend the product?