search

Vatinius / pe

0 stars 0 forks source link

Inconsistency in UG examples #11

Open Vatinius opened 1 week ago

Vatinius commented 1 week ago

In the examples section in the UG, the format in which an example is elaborated with is not consistent. Taking the add command as an example, a new user might not know what this example is talking about as there is no further elaboration in the examples section. However for other commands like find, there is further elaboration what the command does in the examples section.

Add command:

image.png

Find command:

image.png

nus-se-bot commented 1 week ago

Team's Response

The examples are self-explanatory, e.g. add n/John Doe p/98765432 e/johnd@example.com b/100,000, it is clear that this will add a buyer with the name John Doe, as it is an input after the parameter n/ which stands for NAME in the instructions format, the phone number will be 98765432, etc...

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: Thank you for your response! However, I disagree this response. Taking the Edit command examples as show in the screenshot below, shouldn't the same logic that your team has mentioned in your response be applied to all the other examples as well? As seen in the first bullet point below, p/ and e/ should have been self-explanatory to the reader, yet there was further elaboration that the phone number and email. As a new user, it is rather unfair that I will have to make assumptions in the User Guide, and might be thoroughly confused. Hence, I would still classify this as an inconsistency in your UG example formatting.

At the very least, I believe that this issue should have been classified as Not In Scope instead.

Screenshot of Edit command, with highlighted portion showing inconsistency in argument that fields for p/ and e/ are intuitive and should not be elaborated on:

image.png

## :question: Issue severity Team chose [`severity.VeryLow`] Originally [`severity.Medium`] - [x] I disagree **Reason for disagreement:** Thank you for your response! However, I disagree with the severity your team has chosen. I do not feel that it is of Very Low severity as it is not a cosmetic bug. The inconsistency in the examples can confuse some new users who are reading the UG for the first time, or for the first few times, as according to the team's reply, they are expected to find the examples "self-explanatory". Should they not be able to infer the meanings, they can definitely be confused. At the very least, I feel that it should have been classified as a Low severity.