search

avielcx / pe

0 stars 0 forks source link

Wrong instruction in UG #3

Open avielcx opened 1 year ago

avielcx commented 1 year ago

image.png

it is not java -jar NUSTo-DoList.jar

but

java -jar [CS2113-T11-4][NUSTo-DoList].jar

The severity is high given that users might not have experience with CLI and get stuck using the program from the very start. Personally spent quite some time (in the context of an exam) troubleshooting it

nus-se-bot commented 1 year ago

Team's Response

This instructions are based on our Github release. The name of the jar file provided in the PE was based on the naming conventions required for the PE.

We believe that users who download our jar file from Github will not face this issue, thus we have changed the severity to Low.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: Understand that these instructions are based on your Github release. The name of the jar file provided in the PE was based on the naming conventions required for the PE.

However, users can name their jar file however they like when downloading it. Users, especially new users, may not think the file name must be written in the terminal to start the program. As such, they might still follow your UG/DG instructions even though the name has changed.

For example, users might change their jar file name to duke.jar. But they still copy and paste your UG/DG instructions thinking that that command is a fixed command regardless of file name. As such, this wastes a significant amount of time for users before they begin to associate the file name with the initialization of the program

One way I suggest is to be explicit and general about the initialization:

java -jar FILE_NAME.jar

And give an explanation.

Otherwise, I do believe it to be a serious documentation flaw, given that once users cannot initialize due to the lack of instruction clarity and users not willing to troubleshoot, the program is obsolete.

## :question: Issue severity Team chose [`severity.Low`] Originally [`severity.High`] - [x] I disagree **Reason for disagreement:** This is not a low severity, given that once users do not understand how to initialize the program, the program is completely obsolete. In the context of a UG and given developers' target users who might be inexperienced with programming, in particular, users will be immediately repulsed by the program and not even try to troubleshoot.