Project Artifacts

A project artifact is a website containing your project's documentation, organized in such way to allow another programmer (i.e., a professor or TA) or user (i.e., a potential customer) to quickly understand your program and easily find any detail or how to use it. It is your responsibility to determine a useful order for the sections in the artifact, simply putting them in alphabetical order is not sufficient.

Your artifact must include at least three sections: a user's manual, programmer's manual, and source code documentation. You may certainly include more it you are inclined to do so. You must include everybody's name that worked on the project, including outside people with whom you collaborated, on everything that you create.

User's Manual

A user's manual describes the features of your project to non-programmers, so they will know how to use your project and what to expect from using it. Specifically, your manual should describe

• the exact commands needed to run the program, including examples of its various command-line arguments (if appropriate)
• what output the user can expect from the program, specifically you should show a sample run of the program
• how the program deals with errors and how to understand your error messages
• what features the program includes (especially highlight the ones that set your project apart from its competitors)
• what features may be coming in later releases of the program
• any other caveats of which the user should be aware (i.e., environment variables, resource files, data files, etc.)

Here are some examples of user manuals from previous semesters. These examples are not endorsed in any way, but are meant to serve as an example.

• Functional documentation (Reasonably complete)
• Functional documentation (Also reasonably complete, with slightly more help)
• More bells and whistles (Reasonably complete, but the supported program has some extensions)
• Bells and whistles (Very spiffy documentation)

Programmer's Manual

A programmer's manual paints a big picture of the design and creates a map of your project for other programmers, so they will know where to look to fix bugs, make additions, etc. Specifically, your manual should include

• a description of all necessary files associated with the project
• a short paragraph high-level description of the design of your program
• a more detailed description of your design, perhaps including a picture of how the various packages are related
• any design decisions that the group discussed at length, include pros and cons from all sides of the discussion
• some example scenarios of how your system handles specific use cases, especially extending your system as discussed in the assignment handout
• any bugs remaining and how you might fix them
• any features remaining that you have thoughts about how to implement

Here are some examples of programmer manuals from previous semester. These examples are not endorsed in any way, but are meant to serve as an example.

• Passable documentation (Reasonably complete)
• Functional documentation (Also reasonably complete, with slightly more help)

Source Code Documentation

Finally, you should generate HTML documentation for each public package, class, function, and constant within your project. For each component of your system, you should describe its purpose, interface, invariants, dependencies, and any other details users of the component should know.

You can use a program like doxygen for C++ and javadoc for Java to document your public classes, methods, and variables. These programs extract your comments written directly within the code and forms them into a collection of web pages. These programs are available on acpub or for download to your local machine.

To mark which comments should be used for such documentation, use a variation on block comments as shown below (note that the block starts with two asterisks)

/**
 * For this comment to appear in the web page documentation,
 * it must start with an extra star.
 */

README

You should create a README file. It is called a README because, with many pieces of software, there is such a file included which explains how to compile, run, and test the program. If the project includes multiple directories, it should also describe the purpose of each directory and how the files are organized, including what files are important for your project. Finally, it should include details about this how to customize the software for a new environment (i.e., a different directory, platform, etc.).