search

drustanyjt / pe

0 stars 0 forks source link

Bolt command section does not say how to unbolt #12

Open drustanyjt opened 7 months ago

drustanyjt commented 7 months ago

Documentation Bug Description

A reader who is viewing the bolt command won't know how to lower bolt count:

image.png

This question is NEVER DIRECTLY ANSWERED (note even in the FAQ).

image.png

Expected

Some tip in the bold command section of how this can be changed.

Severity

severity.Medium : A flaw that causes occasional inconvenience to some users, but they can continue to use the product.

Not a purely cosmetic issue in docs or UI, since it affects readability, so cannot be VeryLow. As a user, one might be very bewildered because you would need to have read the edit section, realised that there is no way to "unbolt" and then realise that you can do this using edit, without it ever been told to you. In my mind, this is inconvenient enough to warrant a Medium.

soc-se-bot commented 7 months ago

Team's Response

Hello, thanks for bringing this inconsistency to our attention. However we don't think that the consequence is as dire as reported.

  1. Regarding the FAQ on the star command, although bolts are not mention, it would not be too far-fetched to suggest that the reader would also assume that the edit also works on bolts.
  2. We are assuming that the reader has read the entire documentation and would know what the edit command is for.

We'd like to seek clarification on what you mean by the following:

As a user, one might be very bewildered because you would need to have read the edit section, realised that there is no way to "unbolt" and then realise that you can do this using edit, without it ever been told to you.

The 'Original' Bug

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

No good way to remove stars/bolts from people

Since star and bolt only take in positive integers, any form of taking away stars/bolts requires the edit command. which can be troublesome if you don't know the student's current star count. This may make it difficult for teachers that want to punish bad behaviour as well as reward them.

[original: nus-cs2103-AY2324S2/pe-interim#2379] [original labels: severity.Low type.FeatureFlaw]

Their Response to the 'Original' Bug

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

Hi, thanks for the suggestion. Not allowing adding of "negative" stars was our design decision from the start when adding the stars feature, since the inclusion of negative numbers into command may be confusing for some people in our target audience.

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: >Hi, thanks for the suggestion. Not allowing adding of "negative" stars was our design decision from the start when adding the stars feature, since the inclusion of negative numbers into command may be confusing for some people in our target audience.

Firstly this is a bug about bolt so your response to the original bug (only talking about show) does not really address my concern.

Secondly this bug is not saying that "negative" bolts should be allowed. I'm saying that as a user, I would have liked to know how to undo a bolt, which you don't directly mention anywhere in the UG (ie. this is a documentation problem). In particular, your FAQ section mentions that you can change the value of stars through the edit command, but not bolt, so a user might be misled to believe that there is no "proper" way to remove a bolt except through some kind of hacks. This is untrue because there is in fact a way to change the value of a bolt through the edit command. So the fix for this would have been adding a tip of some sort for this scenario, or even adding an extra mention about this in the FAQ, and then adding a link to the FAQ in the bolt section.

## :question: Issue response Team chose [`response.NotInScope`] - [x] I disagree **Reason for disagreement:** The team did not really say why this is NotInScope. Actually they seem to acknowledge there is some inconsistency errors: >Hello, thanks for bringing this inconsistency to our attention. I feel that this could have been easily resolved by adding a tip in the `bolt` section (at most 1-2 sentences). This seems like a rather trivial addition, so if the team believes this is something they would have wanted to do, it should not be NotInScope.
## :question: Issue type Team chose [`type.FeatureFlaw`] Originally [`type.DocumentationBug`] - [x] I disagree **Reason for disagreement:** >Hi, thanks for the suggestion. Not allowing adding of "negative" stars was our design decision from the start when adding the stars feature, since the inclusion of negative numbers into command may be confusing for some people in our target audience. This bug is not saying that "negative" bolts should be allowed (which would be a feature flaw). I'm saying that as a user, I would have liked to know how to undo a bolt, which you don't directly mention anywhere in the UG (ie. this is a documentation problem). In particular, your FAQ section mentions that you can change the value of stars through the `edit` command, but not bolt, so a user might be misled to believe that there is no "proper" way to remove a bolt except through some kind of hacks. This is untrue because there is in fact a way to change the value of a bolt through the `edit` command. So the fix for this would have been adding a tip of some sort for this scenario, or even adding an extra mention about this in the FAQ, and then adding a link to the FAQ in the `bolt` section.
## :question: Issue severity Team chose [`severity.Low`] Originally [`severity.Medium`] - [x] I disagree **Reason for disagreement:** >As a user, one might be very bewildered because you would need to have read the edit section, realised that there is no way to "unbolt" and then realize that you can do this using edit, without it ever been told to you. Consider the affect on an unexperienced user (every user at one point must be inexperienced, so this is a large group). They have just read through the instructions in the `bolt` section on adding bolts to a student. The first thing they would likely do is look through the rest of the specification of the `bolt` section, to see if there are instructions on how to decrement a bolt and find no mention about how bolts can be decremented. The next place to look for questions to be answered would be the FAQ, and since that is included, they would scroll down to the FAQs to look for it. Importantly, **the user notes that there are instructions to remove a star, but no mention at all of removing a bolt**. This is abit like the SWE idea of increasing cohesion. If the information is too far apart, the reader has to put in more effort than necessary to put the information together to realize how he can remove bolts. >it would not be too far-fetched to suggest that the reader would also assume that the edit also works on bolts. I don't think this assumption is that likely. Given the context of an inexperienced user, they might just think there is no "proper" way to decrement bolts. Even if they do realize that `edit` allows you to edit bolts, they might think it was a "hackish" or a "workaround" way of doing things, and forever wonder if there is indeed a "proper" way to decrement bolts. The UG is suppose to after all be the guide to using the app, there is no better way for a user to find out information in the app. While as SWE, we might find this quite self evident, if one is not used to critical thinking/ just wants to use the app, I think they would just want to receive clear instruction on how to solve their most forseeable question. (this is forseeable since after all, you did point out how to remove `stars` in the UG). Given that all users of an app are new users at one point, and this is quite a troublesome problem for many new users, I think this warrants a medium severity. Especially since the fix would not have taken more than a few sentences.