soc-pe-bot
commented
1 week ago Team's Response
Thank you for your feedback. We appreciate your detailed observations and suggestions regarding the comment feature.
We understand your concern that this issue might appear as a feature flaw due to a perceived lack of warning or clarity in the documentation. However, after careful review, we respectfully disagree with this assessment.
In our current User Guide (UG), the COMMENT argument is clearly defined as referring to "any input you want to use as a comment." This indicates that the comment entered by the user will replace any existing comment, and it does not suggest that the input will be appended to or edited in an existing comment. Additionally, the UG explicitly states that each student can have only one comment, which inherently implies that adding a new comment will overwrite the previous one.
Based on the definition provided in the UG, we believe that it is understandable that new comments will replace old ones. However, we acknowledge that there might still be room to make this behavior even more explicit to avoid any potential confusion.
Therefore, while we maintain that this is not a feature flaw, we are willing to classify it as a documentation bug based on your feedback and your description "Description: UG with the command comment does not indicate that new comments will override the old comments and only state that each student can only have 1 comment" and suggestion "Perhaps update UG to talk about how the it overwrites the comments and warn readers or throw a warning". The current UG could be enhanced to explicitly highlight that adding a new comment will overwrite the existing one, ensuring that this behavior is unambiguously communicated.
Regarding severity, we have categorized this issue as severity.Low for the following reasons:
It does not prevent users from adding or updating comments as intended. The user can still copy any existing comment if they wish to preserve it before adding a new one.It only causes a minor inconvenience, as confirmed by our user acceptance testing, where participants understood that the command behavior implied overwriting based on the current definition.
We appreciate your suggestion and will update the UG to clarify this functionality in a future release to make it even more explicit than it currently is on how comment overrides. Thank you again for your valuable input, and we are committed to continually improving our documentation to enhance user experience.
Items for the Tester to Verify
:question: Issue type
Team chose [type.DocumentationBug]
Originally [type.FeatureFlaw]
- [ ] I disagree
Reason for disagreement: [replace this with your explanation]
## :question: Issue severity Team chose [`severity.Low`] Originally [`severity.Medium`] - [x] I disagree **Reason for disagreement:** severity.Medium: A flaw that causes occasional inconvenience to some users, but they can continue to use the product. Although it does not prevent users from adding comments as intended hence they can continue using the product, users are unaware of the replacement policy of comments as it is not indicated in the UG implicitly or explicitly. (I disagree with the developing team that those 2 statements have any indication of overwriting of comments) 1. "any input you want to use as a comment." - simply states that i have no limitation in what i can put as a comment in the application 2. "the UG explicitly states that each student can have only one comment" - this imposes a rule which i would expect an error to appear if the rule is broken. Nevertheless, the replacement policy is not specific at all. Since users are unaware that their comments will be overwritten, they will not think about copying existing comments if they wish to preserve them. Users may also accidentally add comments to another student that already have a comment, causing potential valuable data to disappear without the users knowing since they are unaware of the overwrite and this would continue to happen until they realized that the comments are being overwritten. This would pose occasional inconvenience as they are unable to retrieve the old comments anymore. Also, suppose the users are aware of the comments being overwritten and wishes to preserve their old comments, they would have to manually type out the old comments they have written to another application since the application user interface does not allow highlighting of texts, making it extremely troublesome for long comments.
Description: UG with the command comment does not indicate that new comments will override the old comments and only state that each student can only have 1 comment
Expected: Certain error message stating that the entry already contain 1 comment or the UG warns user that adding a new comment will override the old one
Actual: Old comment is immediately being overwritten
Before
After
Steps to reproduce:
comment 15 c/hello
comment 15 c/bye
Suggestion: Perhaps update UG to talk about how the it overwrites the comments and warn readers or throw a warning