search

lfrostbytee / pe

0 stars 0 forks source link

User Guide multiple keywords error #9

Open lfrostbytee opened 2 years ago

lfrostbytee commented 2 years ago

The User Guide specifies that:

image.png

However, the find command works for more than 2 keywords.

image.png

Yet in the User Guide, [MORE_KEYWORDS] is optional when perhaps the ... symbol could have been utilised instead. This may cause confusion to the reader as they may think that the find command can only have 1 or 2 keywords.

image.png

nus-pe-script commented 2 years ago

Team's Response

Not a bug, as [MORE_KEYWORDS] is plural and should be rather obvious for the user.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: Unfortunately, I don't think [MORE_KEYWORDS] being plural is obvious for the user. I believe that since I and some members of the developer team are familiar with AB3, the developer team's response might seem intuitive because AB3's User Guide phrases the find command similarly and also accepts multiple keywords.

However, to a user that has never used AB3 before, or even the Pupilist application, the [MORE_KEYWORDS] may not be intuitive to them at all. Since the start of the group's User Guide has made explicit mention that "Items with ... after them can be used multiple times including zero times" and that the tag command utilises this notation, I believe that for consistency, adding "..." behind [MORE_KEYWORDS] in find helps improve the quality of the documentation.

Example 1:

image.png

Example 2:

image.png

Not including "..." after [MORE_KEYWORDS] can also confuse the reader because they may not know that they are allowed to have more than 2 keywords for the find command.

Since the scenario in which this occurs is rare, therefore, I believe this is a Low severity Documentation Bug.