search

Eugenetanwl3881 / pe

0 stars 0 forks source link

Certain parts of the UG were hard to read #14

Open Eugenetanwl3881 opened 2 years ago

Eugenetanwl3881 commented 2 years ago

There are sections of the UG where commands get very long and it looked messy and was hard to read. I appreciated the colored breakdowns of the command and believe that it should come earlier on before the examples to give more clarity/ ease of reading.

image.png

image.png

nus-se-bot commented 1 year ago

Team's Response

Further clarification

Hello, thanks for the issue raised. We put examples before the color breakdown as it is natural to tell the users what it is (the examples), before explaining how it works (the color breakdown).

Screenshot

image.png

Reasons for it being a duplicate of another bug report

They are all about how difficult it is to understand the add-related commands and its sample commands in UG.

The 'Original' Bug

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

The whole add command in UG is very difficult to understand

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.

As a user, the whole add-related command section is very messy. It either take the user a long time to understand how it works or could not understand at all.

I personally think it is medium but I put it as low because even if the user do not understand how to type the add command, they can still use the add pop out window for buyer and supplier.

[original: nus-cs2103-AY2223S1/pe-interim#247] [original labels: type.DocumentationBug severity.Low]

Their Response to the 'Original' Bug

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

Clarification

Hello, thanks for raising this issue. We are fully aware that examples of some command can be lengthy and need some time to understand (add a buyer with two orders and add a supplier with two pets, to be specific). That is the reason why we include the color-coded version of these commands in our UG, as you can see in the screenshots below. This will help the users understand what these commands mean more easily.

Screenshot

image.png

image.png

More clarification

Furthermore, we stated in the UG that inexperienced users are encouraged to use the add command with a popup window, so this part is meant for more advanced users, as given below.

image.png

As explained in the user guide and the developer guide, chaining multiple commands to get a long complicated command in one shot is an optional bonus for those who are familiar with the operations. For other fast typists who are reluctant to understand it or key in many prefixes, then can choose to enter the commands one by one instead of chaining them together. Alternatively, they can use the pop-up window, too, which does not require users to type any prefix at all.

We also left enough hints and advice to readers that if they are not comfortable with these prefixes, and can try the pop-up window that does not require prefixes. We even provided them with a link directly to the section on how to use the pop-up window.

image.png

image.png

Reasons for lowering the severity

Some readers can understand the add command. Some may love it and stick to it. For those who are not comfortable with it, we have provided them with enough visuals to aid our explanation, and hints about other alternatives. We believe that even if this is really a bug, it is a cosmetic problem. Our layout, colour-coding, order of sections should be designed better (as you mentioned, "messy"). Hence, it is a bug of very low severity.

Thank you again and have a nice day!

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)

  • [ ] I disagree

Reason for disagreement: [replace this with your explanation]

:question: Issue response

Team chose [response.Rejected]

  • [x] I disagree

Reason for disagreement: Similar to the duplicate bug flagged, I also feel that the UG was very hard to read and digest as a user (especially the add command). Even with the admonitions and color coding, the section was still cluttered and hard to follow. Even after the PE, without time constraints, I found it hard to read through these sections of the UG. The unintuitiveness of the commands makes this even harder. It is not user-friendly, hence I would have to disagree (Severity.VeryLow is given here since I believe the cluttered content and messiness of UG made it hard to read)