Make progress on the implementation of your project and solidify the documentation for users and developers.
Work with your project group to (1) make progress towards the final release, (2) provide comprehensive user documentation, and (3) provide comprehensive developer documentation.
Due Tues 11/14/23 11:59pm PT. Submit to Canvas and in GitHub as directed (check Calendar for any updates).
Your repository must contain a complete user manual. Anyone looking at your repository should be able to easily find the user manual. The user manual is focused solely on the people who want to install and use your product.
The user manual should describe the functionality of your project as you expect it to be at the end of the quarter. For this assignment, indicate missing functionality as work in progress.
The user manual should include at least the following information:
A high-level description. What does the system do and why would a user want to use it.
How to install the software. If your system has prerequisites (e.g., tools, libraries, emulators, third-party applications, etc.), your instructions should list all of them and indicate how to install and configure them. Make sure to indicate what specific version requirements these prerequisites must satisfy. If running the system requires the installation of, e.g., a virtual machine, a database, or an emulator, make sure to provide clear step-by-step instructions.
How to run the software. How to start up the system?
How to use the software. You can assume that your user is familiar with your particular platform (e.g., use of a Web browser, desktop applications, or mobile applications). For missing functionality, your documentation should simply indicate that this functionality is work in progress.
How to report a bug. This should include not just the mechanics (a pointer to your issue tracker), but also what information is needed. You can set up a bug-report template in your issue tracker, or you can reference a resource about how to write a good bug report. Here is an example for bug reporting guidelines.
Known bugs. Known bugs or limitations should be documented in the bug tracker. A user testing the implemented use case(s) should not encounter trivial bugs (e.g., NPEs) or a large number of bugs that are unlisted in your bug tracker.
Complete this in the main branch of your repository by the due date.
Your repository must contain developer guidelines. Anyone looking at your repository should be able to easily find these guidelines. The developer guidelines are focused solely on people who want to contribute to your project.
The developer documentation should include at least the following information:
How to obtain the source code. If your system uses multiple repositories or submodules, provide clear instructions for how to obtain all relevant sources.
The layout of your directory structure. What do the various directories (folders) contain, and where to find source files, tests, documentation, data files, etc.
How to build the software. Provide clear instructions for how to use your project's build system to build all system components.
How to test the software. Provide clear instructions for how to run the system's test cases. In some cases, the instructions may need to include information such as how to access data sources or how to interact with external systems. You may reference the user documentation (e.g., prerequisites) to avoid duplication.
How to add new tests. Are there any naming conventions/patterns to follow when naming test files? Is there a particular test harness to use?
How to build a release of the software. Describe any tasks that are not automated. For example, should a developer update a version number (in code and documentation) prior to invoking the build system? Are there any sanity checks a developer should perform after building a release?
Complete this in the main branch of your repository by the due date.
When you finish all the tasks above, copy to Canvas the version id that identifies this release (see Git Tagging).
Make sure the last commit in this version is inside the due date timeline! The staff will be grading your submission based on this committed version of your release.
Think of the user as someone to whom you might sell your system software. They will want to understand what it does, how to install it, how to use it including what features are present and future, and how to file bugs against it. For instance, if your solution is a course scheduler, the user might be a university administrator.
The documentation in your repository should be largely self-contained, and anyone looking for documentation should find it, or a link to it, in the repository.
You may link to sections of your living document from your user/developer documentation, or you may move these sections to the repository and put a link to it in your living document.
Do not maintain two parallel versions of any documentation. But be clear on where the user/developer information can be found.