The system manual may be structured as follows
- Installation and Usage
- Implementation Overview
- Test Results
Content Type(s): text, pictures, tables, source code snippets, ...
Length: several pages to tens of pages
Installation and Usage
Assume students in next years senior project need to install your system on a new computer. The Installation section should list the steps to complete the installation. You do not need to give detailed steps of installing other peoples software (e.g. how to install MySQL server), only your own software/hardware. You should refer to specific files/directories in your electronic source code submission. For example:
- Install MySQL database server and Apache web server
- Import the database src/db/maindata.sql into MySQL
- Edit the file src/www/config.php to include appropriate database and password
- Copy all files from src/www/ into the web server base directory
- Access the website at http://example.com/courseeval/
- Login as “admin” with password “123456” and select a new password
You should also explain important or non-obvious ways in using the system. Note that this is NOT a User Manual or help section: it does not have to cover all steps in using the system. For example, if you develop a website you do NOT need to explain the obvious features (such as login, search, sorting data, editing in forms). Instead explain only the non-obvious features. For example if you have a search feature on your website, and have included your own special query syntax, then explain that syntax.
If you have developed standalone software and/or hardware, you should explain how to start it. For example if your software is run on the command line, then give the syntax and main command line options for using it.
Do NOT include screen-shots (unless very useful in explaining non-obvious features).
A brief description of implementation-specific issues with your system. In other words, describe important aspects of the system that someone needs to understand the implementation, that are not already described in the Design Specification (do not repeat what is already in the Design Specification). You may start with a diagram or description that relates the architecture design with the source code that you developed. For example: “The user login module is implemented in the file login.php, while the statistics processing module is in the set of files starting with stat_.”
An important part of this section is a list of the software/hardware components that you used, including versions. For example:
“Our website made use of the following software:
MySQL server version 5.5
Apache Web server version 2.4.1
Ubuntu Linux 14.04 LTS operating system”
This Implementation Overview is valuable for students in subsequent years that may need to view, understand and modify your code.
Do not include complete source code as that is submitted electronically. However you may refer to source code, either as a files or in source code snippets.
A description of how you tested your system and what results were obtained. Consider the online course evaluation example. The website may be tested at different levels, including by potential users. Testing using fake data sets may be performed to check that the statistic calculations are correct. The data sets used should be described in the Test Results section. Testing by different users (students, admin, lecturer) may be performed to check that the features/workflow is as required. The number of users and how they tested should be described in the Test Results section.
Tests may be described informally (e.g. using text like “We asked 5 students to complete evaluations of 3 courses over a 1 week period. The feedback from the students was used to improve the website, in particular reducing the number of clicks needed to complete the evaluation from 5 down to 2.”) or formally (e.g. using tables of tests and results).