Unclear explanation for example for Mark Command

[lim-jt]

The phrasing of the following explanation for the example suggests that "a different GUI" will be displayed if used on a different day that is not 7th November 2024.

Firstly, it would be clearer to specify what "a different GUI" means, which users will have to infer to be the tick to indicate marked attendance on the GUI from the later screenshots and tips.

Secondly, the example suggests that the tick will only appear if the date is 7th November 2024, which is incorrect as it should refer to the current date when the command is used.

Severity is low as the explanation after this section of the UG clarifies the above allows users to infer the meaning of the example, but there is still a possibility of confusion due to the conflicting meanings!

[soc-se-bot]

Team's Response

Thank you for your feedback. We would like to address the potential misunderstanding regarding the example and the explanation provided.

Firstly, the example command mark t/alexYeoh t/berniceYu d/2024-11-07 is indeed designed to illustrate that the box will only be ticked if the date is specified as 2024-11-07. This is consistent with the way the command format works in practice—marking attendance only for the specified date. Therefore, the statement, "the example suggests that the tick will only appear if the date is 7th November 2024," is correct based on the context of the example.

Secondly, if users test this command and compare the GUI output with the provided example image, they will observe that the box is not ticked unless the current actual date they input this command matches 2024-11-07. The note below this example further clarifies under what conditions the box is ticked. The User Guide also details how the mark command functions, and the parenthetical note (other than 7th November 2024) points out where differences in the GUI might arise in a straightforward manner. These elements should minimize any potential confusion.

We believe the current explanation is clear, but we appreciate your concern.

Items for the Tester to Verify

❓ Issue response

Team chose [response.Rejected]

• I disagree

Reason for disagreement: I still believe that the wordings of the example is unclear/ambiguous and may invite misunderstandings as there could be a few interpretations of what it means:

1. The example code will display a different GUI (compared to the screenshot in the UG as provided by the Dev Team which has tickboxes) i.e. GUI has no tickboxes if a different date is used in the code instead of 2024-11-07. This is a wrong interpretation of what as it suggests that the mark command only shows tickboxes when the specific date 2024-11-07 is used.

2. The example code will display a different GUI (compared to what the user sees when using the example code which will not have tickboxes) i.e. GUI has tickboxes if the user uses the command on a different day. This is a wrong interpretation of what different GUI means. Additionally in the PDF there is a page break after the example code before the screenshot is shown, which users may not link to the screenshot GUI.

3. The example code will display a different GUI (compared to the screenshot) i.e. GUI has no tick boxes if the users uses the command on a different day. This is the correct interpretation.

As can be seen above, the ambiguous wordings of the example can lead to misunderstandings which can easily be resolved by being clearer in the example of what a different GUI meant and that the screenshot example is in the assumption that the command was used on the same date as specified in the command.

The note mentioned by the Dev Team clarifies this, but I believe that this does not take away the fact that the example was confusing and require users to fill in the gaps and infer from the note which interpretation of the example is the correct one, when it should be made clear from the original example.

---