nus-se-bot
commented
1 week ago Team's Response
Thank you for our suggestion regarding our quickstart.
Instructions on the system requirements were already given. If the user were to follow the quickstart step by step, the application would launch as expected.
Items for the Tester to Verify
:question: Issue response
Team chose [response.Rejected]
- [x] I disagree
Reason for disagreement: Thank you for your response regarding the Quick Start guide. While I understand that the instructions provided should, in theory, work if followed step by step, it is important to account for the diversity of technical proficiency among users, particularly private tutors who may not have extensive experience troubleshooting issues in a terminal or PowerShell.
Although the instructions on minimum system requirements ensure the correct Java version is installed, the issue I am raising pertains to potential problems that may arise during the use of the terminal or PowerShell. These scenarios are particularly relevant for private tutors in real-world use cases.
Encountering an error without prior warning or guidance can be intimidating, especially for users with limited technical knowledge. Providing examples of potential error messages, along with reassurance that these issues can be resolved, would instill more confidence in users to troubleshoot rather than abandon the application altogether.
For instance, users may encounter common terminal errors such as:
File not found: This may happen if the .jar file is not placed in the specified directory or if the file path is mistyped. Java command not recognized: This error suggests that Java is not properly installed or that it is missing from the system’s PATH environment variable. Permission errors: Some systems may require administrative permissions to execute commands. These scenarios, while not frequent, are not uncommon either. Including a brief troubleshooting section in the Quick Start guide to address these potential issues would significantly enhance the usability of the program. This approach would also make the documentation more self-contained and accessible, reducing the need for users to seek external support or give up on the application altogether.
Like the other issues raised, I believe the severity of this documentation bug is low since most users should be able to navigate through the instructions provided with some tinkering. However, rare cases like the ones mentioned above could lead to frustration if users encounter errors, search through the User Guide for solutions, and realize no relevant information is provided. This lack of clarity could result in users either spending unnecessary time searching for solutions online or abandoning the application entirely.
There should be more information in the quick start guide after point 5.
More specifically, it would help the private tutors who are planning to use the program as to what are the common issues that they may face whilst trying to open your program especially for people who do not have in-depth knowledge the error messages that might pop up while using the terminal to open up the program.
This gives reassurance that it is not a problem that is specifically faced by them and allows more information to be self-contained in the user guide and makes the private tutor more likely to try and troubleshoot the issue rather than just not troubleshoot at all and not using the program altogether.