Note: all documents described below are located in the repository and are clearly titled, thus they will be distributed along with the rest of the application when handed off to the client. Furthermore, the README contains pointers to each of the 3 documents at the very beginning.
Our team is upgrading and enhancing the backend database for the OMLSMS by updating its Python version to Python 3. We are also updating versions of Django and PyQt within the project. Below is our plan for providing documentation for 3 types of individuals – administrators of the system, typical users, and those who may be working on the code itself in the future. For all users, we plan to write README markdown files within the repository to execute our plan, as well as create Word documents; this is how our team received most of our information.
Administrators
Administrators will need to know how to set the system up in the future in order to maintain it, even in the event that they do not have access to the repository (and therefore not the README). Therefore, the admin documentation will be a word doc basically describing how to set up the system from scratch, given only a SQL Server backup file. Additionally, it will also describe the various settings that may need to be changed in the code to correspond to the SQL instance, and what those settings mean. The main concern here is that administrators know how to install the application as well as maintain it in case any settings change in the future.
Employees
Users of the application without administrative permissions will need to know how the newly upgraded interface works, and how it interacts with the underlying database. If any significant changes are made in this process, we plan to write about it extensively in our documentation. A word doc was included in the original version of the application that was written, but it was fairly outdated and did not reflect our changes. Therefore, for users, we will not only be updating this word doc for users and including it in the repository, but we will also make a video that details specific steps for a user to follow to install the system. After it launches successfully, the word doc for users should cover enough broad information about the system to help them understand it.
Programmers
The main goal here is to help future programmers working on this project run into far less difficulty than we ran into by giving them proper documentation. Since we are updating the entire architecture of the application, we will need to document any major changes made. For example, if there is a feature within older versions of PyQt, Django, or Python that has since been deprecated, we will need to let all the users know how we were able to work around this and if it affects how the user interface looks or functions. We will need to describe and go into detail on what functionality we added, replaced, or removed altogether. We will utilize upgrading this application to ensure thorough documentation of the application to decrease friction for employees and ensure maintainability for admins and users. In addition to the actual code-level documentation, we will also make a detailed Design Document linked in the README for any programmer to follow and learn about the project structure itself. Furthermore, the README, which programmers will have access to, will contain detailed steps about getting the system to successfully run on their local machines so that they can work on it in the future.