search

heejet / pe

0 stars 0 forks source link

Wrong file name in the user guide #11

Open heejet opened 1 year ago

heejet commented 1 year ago

In the Quick Start section of the user guide the file name is [CS2113-T12-4][WellNUS++].jar. However the actual filename in the link provided was CS2113-T12-4.WellNUS++.jar.

I think this is a common issue where GitHub automatically removes any special characters.

User unfamiliar with java could be confused and unable to use your application.

image.png

image.png

soc-se-bot commented 1 year ago

Team's Response

Similar to the original issue #1915. Refer to that issue for further details.

The 'Original' Bug

[The team marked this bug as a duplicate of the following bug]

The name of jar in manual testing is wrong.

Note from the teaching team: This bug was reported during the Part II (Evaluating Documents) stage of the PE. You may reject this bug if it is not related to the quality of documentation.

In the DG/UG, the name is: [CS2113-T12-4][WellNUS++].jar

image.png

But in the github, the name is: CS2113-T12-4.WellNUS++.jar

image.png

[original: nus-cs2113-AY2223S2/pe-interim#2615] [original labels: severity.VeryLow type.DocumentationBug]

Their Response to the 'Original' Bug

[This is the team's response to the above 'original' bug]

Thank you for the suggestion.

The intention for indicating the jar name as [CS2113-T12-4][WellNUS++].jar in our documentation is to match the name of the submitted jar file that testers will be using for our PE, so as to avoid this very issue for eagle-eyed testers.

Unfortunately, despite multiple attempts at uploading the jar file with the original name, GitHub consistently removed the square brackets, which led to the jar file in our GitHub release bearing the incorrect name you found. We are unable to fix this issue since it's due to GitHub's policies, so we elected to reject this issue.

Thank you for the advice regardless.

Items for the Tester to Verify

:question: Issue duplicate status

Team chose to mark this issue as a duplicate of another issue (as explained in the Team's response above)

Reason for disagreement: [replace this with your explanation]

## :question: Issue response Team chose [`response.Rejected`] - [x] I disagree **Reason for disagreement:** I would like to say I fully understand your point of view but due to the implications this mistake might have, I elected to disagree with your position. > Unfortunately, despite multiple attempts at uploading the jar file with the original name, GitHub consistently removed the square brackets, which led to the jar file in our GitHub release bearing the incorrect name you found. We are unable to fix this issue since it's due to GitHub's policies, so we elected to reject this issue. Allow me to offer my perspective on this issue. The intent of this group project is for us to create a product for our **target users** and the PE is just a means to simulate the system and acceptance testing (because the participants in the PE are not necessarily our target audience). ![image.png](https://raw.githubusercontent.com/heejet/pe/main/files/4f1260e5-73c4-4b8a-a5ad-b659d70f0a3b.png) With that in mind, our UG and DG should be **catered for our target audience and not created just for the PE**. If the UG is written well, it would naturally be suitable for usage in the PE. Therefore wording to UG to become only usable in the PE and disregarding the overall context of the tP does not meet the purpose of the tP. Furthermore, the issue with the square brackets only arises because we were given the `.jar` files from canvas and **not** from the link you provided in the UG. Your target users would not have access to the canvas `.jar` files and would only get the `.jar` file from the link you provided in your UG. Therefore, It does not make sense that the file name written in the UG and the filename in the link provided in the UG are different. This would impact the usability of the application of your actual target users **and is very much a valid issue**. >The intention for indicating the jar name as [CS2113-T12-4][WellNUS++].jar in our documentation is to match the name of the submitted jar file that testers will be using for our PE, so as to avoid this very issue for eagle-eyed testers. If the filename provided in the UG matches the link provided in the UG I am sure testers in the PE would be more understanding of the fact that the the `.jar` file given to us was not the one from the link in the UG and become more forgiving of subtle discrepancies in the filenames.
## :question: Issue severity Team chose [`severity.VeryLow`] Originally [`severity.Low`] - [x] I disagree **Reason for disagreement:** This is not a cosmetic issue because it is a **totally wrong command for starting the application**. The mismatch between the `.jar` file provided and the one in the `UG` would lead to your **actual target users** (not testers in the PE) from being able to use your application. Therefore it is definitely not a cosmetic issue as the implications affects the usability of the application. ![image.png](https://raw.githubusercontent.com/heejet/pe/main/files/fbacc4e4-6e29-4769-a807-b48d381e1083.png) Therefore, `severity.Low` would be a more accurate description of the bug because first time users might copy and paste the command given in the UG and encounter an error. They will then have to scrutinize the file name (which they got from the link provided in the UG) and the command provided in the Quick start section of your UG resulting in inconvenience caused to the reader.