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 should 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 their associated 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. Note, if you can demonstrate that you understand how you should have designed your program, even if you did not successfully get it done, you will get more credit than if you do nothing.

Specifically, your manual should describe

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 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 that starts with /** and ends in the standard */. For example,

/**
 * For this comment to appear in the web page
 * documentation, it must be enclosed in special
 * symbols.
 */

README

For each directory in your project, 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 there are multiple directories it might also describe how the files are organized. Finally, it should include details about this how to customize the software for a new environment (i.e., a different directory, platform, etc.).