search

optionalemon / pe

0 stars 0 forks source link

Inconsistent format in UG `edit command` #10

Open optionalemon opened 1 year ago

optionalemon commented 1 year ago

In the format specified earlier, it is mentioned that <PERSON INDEX> should be placed at the back. Screenshot 2022-11-11 at 17.11.39.png

However in the example, <PERSON INDEX> has been shifted to the very front. Screenshot 2022-11-11 at 17.11.49.png

I am not sure if this is the reason that caused all the functionality bugs regarding to edit command just now (Can't go back to the app to test now). If it is, maybe you can justify by claiming it is a documentation flaw.

As the error has made users almost incapable of using edit command in worst case, I would label as a medium.

nus-se-bot commented 1 year ago

Team's Response

Although the edit person command format in the UG is incorrect, the help message shown to the user in the application is correct.

Hence, they can always refer to that (and so, the error does not "make users almost incapable of using edit command" as we proactively prompt the user to run edit person --help to view the help message.

Hence, it is a low severity documentation bug as it only causes minor inconvenience in rare occasions (moreover, the user can simply delete and add the person in the highly unlikely event that they cannot use the edit person command)

The 'Original' Bug

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

edit person command not working

Screenshot 2022-11-11 at 16.24.56.png

Screenshot 2022-11-11 at 16.25.40.png

Screenshot 2022-11-11 at 16.27.01.png

Tried the aliases in the user guide on the example in user guide, but none of them seem to work.

[original: nus-cs2103-AY2223S1/pe-interim#3540] [original labels: type.FunctionalityBug severity.High]

Their Response to the 'Original' Bug

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

Hi, thanks for the bug report!

This is in fact, caused because of not putting quotes around the names rather than the commands not working. We accept that the commands given in the UG are missing quotes and so, this is a valid bug.

Changed the label to documentation bug to reflect the same. Try edit person 1 -n "XYZ" to verify that the functionality works :) You should see the following output:

Screenshot 2022-11-12 at 5.04.13 PM.png

Changed the label to low for the following reasons:

  1. Although this causes some inconvenience to the user, the help message shown to the user in the application is correct. We also prompt the user (as seen in your screenshots) to run the edit person --help command. The user can simply type edit person --help to view the help message which explicitly includes quotes. Here's an example: Screenshot 2022-11-12 at 5.05.36 PM.png

In other words, this is just an inconsistency between the UG and the actual help command. Since users can always access the help message in the application, we don't think this is a big issue.

  1. The UG also mentions to put quotes for arguments that have multiple words (although admittedly, we forgot to do the same for our examples) in an separate section devoted to explaining the CLI of the application.

image.png

  1. Lastly, if the user does not realise that he/she needs to put quotes in the edit command, he/she can always delete the person and add them back again with the edited details (which causes minor inconvenience).

We hope you understand our rationale

Have a nice reading week ahead!

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: Sorry these are not duplicate issues as the other issue is talking about the fact that example edit person command could not be executed, while this is talking about the difference in arrangement of PERSON INDEX between the given Format section in UG and the Example command.

The last sentence is due to the fact that I am uncertain what is the reason that caused the error in edit person 2 Betsy Crower -t when I was trying it in Phase I, hence I am guessing this inconsistency could be the reason. I did not have time to try it anymore as I was already in Phase II. It appears to not be the reason as well after seeing the group's response, hence I do not see any link between them and do not think they are duplicate issues :(

:question: Issue severity

Team chose [severity.Low] Originally [severity.Medium]

Reason for disagreement: Since the group did not manage to understand the issue and give a convincing response, I would still argue that this is of medium severity.

Using the format specified in Format section, which is having the person index at the back, it outputs an error message rather than a success execution. The team did not specify that the person index has to be at the front in both UG and the application error message, furthermore providing a misleading sequence of arrangement in the Format section. Screenshot 2022-11-15 at 12.48.05.png

It seems like the only correct execution is putting the index at the very front as shown below: Screenshot 2022-11-15 at 12.48.22.png

The information in UG in Format and Example are contradicting, furthermore there is a lack of accurate error message in the application to emphasise to user about this issue. Given these, it may be hard for users to figure that themselves the origin of the error and therefore resolve this issue.

Just like the list name s/don example given on the website, this documentation bug similarly could have caused the user unable to use the edit person command, while the user can continue to use this application. Therefore, a rating of severity.Medium has been given during the PE.