soc-se-bot
commented
4 months ago Team's Response
No details provided by team.
The 'Original' Bug
[The team marked this bug as a duplicate of the following bug]
Unrelated dates and corresponding images in user guide demo [UG]
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.
Within the text, it was mentioned that the deadline was updated on the 31st. However, within the image following the description, the image shows dates from 14 April to 20 April (as shown in the image below).
This can cause confusion for the user as he/she is not sure what the user guide is referring to.
[original: nus-cs2113-AY2324S2/pe-interim#601] [original labels: severity.Low type.DocumentationBug]
Their Response to the 'Original' Bug
[This is the team's response to the above 'original' bug]
This does not affect understanding when reading the UG, though we acknowledge that it is a remnant from an outdated Github deployment.
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)
- [x] I disagree
Reason for disagreement: I disagree because what I am pointing out here is a different issue. The other bug was referring to an unrelated instance of the date and the images occurring in the paragraph that precedes the screenshot.
The problem I am trying to isolate here is the practice of using contextual information and examples within general explanations of a feature. This bug is pointing to an organizational or structural problem with the way the explanations are conducted.
Instead of using specific examples within the explanation for the feature, a better approach would be to give a explanation devoid of examples first, then provide the concrete examples after. The UG would appear better organized and more logically sound this way.
As seen in the image, before the image a description of the updating function for a todo was given. However, there is mentioning of "updated to [new task description] on the 31st".
Even though the user could understand what is expressed from the image that follows, the meaning is not expressed clearly and may mean that any update of the todo will update it to the "31st of that month" if it exists.
Avoid mixing context from specific examples into the general description for a feature or functionality as it may mislead or confuse potential users or readers.