Existing Documentation - camfush/Battleship GitHub Wiki

Written Documentation

A README document has been included in the project, but it does not contain much information. To an inexperienced user, there is not enough information to be able to launch the program easily. For a user looking for more in depth information, the document is too sparse. We should expand this document to both include more comprehensive steps for users who are not familiar with build and run shell documents, and provide a deeper explanation of the program and the requirements to run it.

This may not included in the implementations of this project during this unit, but going forward it would be worth considering creating tutorial documents or videos to further explain all the features of the program to less experienced users.

Code Documentation

The code is already very well documented with comments. Each function and class has a summary of its role and a brief description of how it works. It would be worth including more information before key variables, but apart from this comment documentation is complete.

Other code documentation is not present. If there is time, unit tests should be coded to make sure that all functions are working as expected. The numerous bugs in the system may have been picked up earlier if unit tests had been used. Unit tests will also make it easier for future programmers to identify how the program is expected to work, and identify existing issues as well as their previous status and priority.

Community Documentation

There isn’t any community documentation, and this type of documentation probably isn’t a high priority for the client. It is worth checking this, as they might want a forum where users of the system can ask questions about operation which can be answered by other community members or developers. It would also provide a place for users to report bugs not found during production, making it easier to identify and fix these errors.

As part of our development, we will be creating a GitHub wiki for the project. This wiki will be available both for users of the system, and future developers. This will make it easier for them to identify our process as well as understand the product on a deeper level. As we are developing this wiki for our own convenience as well, making it useful for these other users will not require much additional effort. Although not a priority in this implementation, creating a comment space for users to respond to wiki pages would also allow for a higher level of community engagement.