search

nseah21 / pe

0 stars 0 forks source link

Reference to implementation details in the UG can trip up reader #14

Open nseah21 opened 2 years ago

nseah21 commented 2 years ago

In this section, the UG talks about the limitations of the JavaFX library, which is exposing too much details to the user, who should not have to know about technical details.

This may confuse the reader, and is not purely a cosmetic issue.

image.png

nus-se-bot commented 1 year ago

Team's Response

We feel it is appropriate to explain why there is a white line on a "full" pie chart. This is in fact a purely cosmetic issue and we want to let the reader know that as well.

Mentioning the term "JavaFX library" does not expose the reader to too much detail. We have already refrained from specifying the exact function in the JavaFX library which is causing this visual bug. We are simply telling the reader that this visual bug is due to one of the libraries used as part of our app.

Therefore, we reject this issue as we don't feel that it is a problem at all.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: The user should not be exposed to implementation details in the user guide. The same information could have been easily communicated to the user without any reference to the JavaFX library.

More importantly, the user's attention is intentionally drawn to the term via an alert box, which makes it more likely for them to be confused or tripped up by the term.

Hence, the user is likely to be hindered by this explanation, making this a valid documentation bug.

(Please see the additional details in my justification for the Low severity)

:question: Issue severity

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

Reason for disagreement: > We feel it is appropriate to explain why there is a white line on a "full" pie chart. This is in fact a purely cosmetic issue and we want to let the reader know that as well.

The team seems to be confusing a cosmetic issue in their app with a cosmetic issue for documentation.

Nevertheless, this is not a cosmetic issue as the user's attention is purposely drawn to the JavaFX library, which is an implementation detail that they should not be exposed to. The same information (that the bug occurred due to an underlying bug in the library) could have been made without reference to the JavaFX library.

Mentioning the term "JavaFX library" does not expose the reader to too much detail. We have already refrained from specifying the exact function in the JavaFX library which is causing this visual bug. We are simply telling the reader that this visual bug is due to one of the libraries used as part of our app.

Ultimately, the user should not be exposed to any implementation details in the user guide, as far as possible. This could have been moved to the DG for other developers to consider, replacing the alert with a simple sentence in the UG that mentions how the white line is a known bug that the team is working on.

For the reasons given here, this is not a cosmetic issue, and the severity should be Low instead.