Team's Response

TLDR: read the last paragraph (but do read the entire thing to understand the context).

Thanks for raising this up. The concerns of "what is the difference between [all]... , [contacts]... and [allcontacts]..." didn’t occur to us and while we do not think putting these 3 optional parameters are issues, interestingly not one but two raise the issue relating to the design of list command format, which set us thinking. Perhaps, we will start off with explaining why we have this design choice before addressing your concern at hand.

In the AB3 product, the command for listing all persons is list. The list command is described as a command that does not take in parameters, but if there are any extraneous parameters, the command will accept them anyway and execute the command as if there weren’t any parameters. We describe as such based on the AB3 user guide:

Extraneous parameters for commands that do not take in parameters (such as help, list, exit and clear) will be ignored.

Similarly, we wanted our list command to follow the same design principle as AB3 list command, but instead of just accepting any extraneous parameters, our list command only accept the following extraneous parameters:

all
contacts
allcontacts

Why such specificity, you may ask. One of us feels that the list and find command can be easily mixed up. Think about it, in our product, if we want to list all contacts that has the student status as PhD, we input find ss/Phd. But semantically, this is equivalent to saying list Phd or list Phd contacts. If list accepts any kind of extraneous parameters, it is not very helpful for the user that everytime the user inputs list Phd, all the contacts are still listed and the filter did not take place. Made worse, there isn’t any form of error message but a message that shows insistence to list all contacts. With that in mind, it may be better to just invalidate the command to inform the user from the get go that this is an error.

While one may argue that the user should be intelligent enough to visit the user guide and read them to understand the product behaviour, we wanted to make the product more user friendly by invalidating list commands that are semantically similar to a find command. And our attempt for this is to have such a list command format, as you have experienced using.

That is also why the extraneous parameters we accept are only the three parameters mentioned above -- only those that seem to suggest that the user wants to list all contacts, but probably cannot remember the exact exact command either. This is also the reason why upon entering help list, the description explaining list mentions that this ain’t find: List to show all contacts, as opposed to find command.

Therefore, following the phrasing AB3 user guide uses, we hope you can see the list command as a command that does not take in parameters, but if there are any extraneous parameters, the command will accept only specific extraneous parameters (rather than any extraneous parameters). In other words, our list command is not a command that intentionally has parameters for a reason since these parameters are considered “extra”. Our list command is designed to accommodate some variations only by accepting only certain types of extra.

In order to indicate in a simple manner what the list command format is, we write it as list [all]... [contacts]... [allcontacts]... . These parameters are optional as indicated by the square brackets, and if one decides to write these parameters many many times, that’s fine as well because it is likely that the user intends to list all contacts anyway, so the command will interpret them as just list.

But…it seems that while the command format: list [all]... [contacts]... [allcontacts]... accurately explains the command format allowed, it contains an implied meaning that we did not realise, let alone realising that it will mislead the user’s understanding -- that these parameters, despite it being indicated as optional, are there intentionally for a specific function (?)... which is not the case, as explained above. Note that when we write the command format as such, we feel that indicating optional parameters does not mean that it must serve any purpose, it just mean that we generously allow these words to be entered even though they are not required (thus the word, optional)

Given the benefit of doubt, perhaps the most ideal case would be that we write the list command format as list, but to add notes to it to explain clearly the variations allowed, regardless how lengthy our explanation may be.

Based on this analysis, we diagnose the bug as a Documentation bug -- due to how our phrasing for command format seems to throw people off, despite that strictly in terms of literal meaning, the meaning conveyed is accurate. We believe that this bug’s severity is low because if a user does not over interpret information that is presented, users should have no problems using the product. After all, users can still list all the contacts with our list command. We ensured that what we claimed to be the command format list [all]... [contacts]... [allcontacts]... works as it is. We did not write the list command format wrongly either. This should not affect the normal operations and does not deserve a medium severity.

Conveying the literal meaning of commands format accurately is a standard we abide by for writing the documentation. Writing command formats, or any text, in a way that considers the possible assumptions users may bring (which in this case, the mention of parameters seems to oddly mean that it serves a function) never crossed our minds. After some thought now, while it is valid, it also feels that such exceedingly high standards for writing documentation may be too much of an effort or time to fit into the short timeline we have in creating the product. There are many other more important things to do such as ensuring the function of each feature are implemented well. Therefore, we like to indicate this as response.NotInScope.

In summary, we feel that the real bug is the not-too-ideal phrasing of the list command format, as we believe this is the one that seemingly confuses users. There is indeed no difference between the command formats that included vs not included the accepted parameters, and these parameters indeed do not serve any specific function. The severity should be low, as all the functions are working in order and the point of confusion was due to the user's assumptions on how the format should be interpreted. (assumptions that those parameters mean some intentional function). Writing in a way that considers the user's assumptions requires a large amount of time as time is required to refine phrasing, thus it does not warrant the need to do it before v1.6 or v1.5. Hence, we give a response.NotInScope.

Duplicate status (if any):

Duplicate of #2296

nus-cs2103-AY2425S1 / pe-dev-response

[UG] Ambiguous parameters used for LIST #3269

Team's Response

Duplicate status (if any):