search

gavingoh99 / pe

0 stars 0 forks source link

Descriptions for `find-X` commands can be misleading #13

Open gavingoh99 opened 4 months ago

gavingoh99 commented 4 months ago

Screenshot 2024-04-19 at 5.31.45 PM.png

Screenshot 2024-04-19 at 5.31.51 PM.png

In the UG, the find-X commands are described as providing to ability to find clients whose names / tags contain any of the given keywords.

However, it is later specified that only full words are matched e.g dis will not match disabled. In layman English, a client with the tag disabled does actually contain the keyword dis so we would expect this client to match!

Given the conflicting descriptions, it could be better if the descriptions were changed to match instead of contain!

nus-pe-script commented 4 months ago

Team's Response

"contain any of the given KEYWORDS" implies that whole / full words will be used to match as keywords means "a WORD or concept of great significance", not a part of a word.

image.png

We later even specified that only full words are matched e.g dis will not match disabled.

Since the functionality is accurately described in the detailed section of the documentation, we will not classify this as a bug.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: Thanks for pointing out that keywords should refer to whole words.

Let me posit another example with respect to this:

Suppose a user tags a client with the tag HasADog and decides to search by tag. In this context, surely the word dog is a whole word and also one of great significance. However, SWEE will not match the query with the contact because it does not support substring search.

Again, I'm not disputing that the functionality has been described further down and I've even acknowledged this in my own report. What I'm getting at is that if I were a user in a hurry and only read the first short description under the command, I would be inclined to think that as long as the tag contains the keyword we should expect that SWEE will return said client. The misalignment between this short description and the detailed description can potentially lead to confusion and thus that's why I believe it to be a documentation bug.

## :question: Issue severity Team chose [`severity.VeryLow`] Originally [`severity.Low`] - [ ] I disagree **Reason for disagreement:** [replace this with your explanation]