Edit-related commands format does not follow the real command format.

[david-eom]

Throughout the documentation, it is assumed by the user that anything demarcated within the square bracket e.g. [n/NAME] is an optional field.

However, for all the edit commands, although all fields are optional (e.g. editLink INDEX [n/NAME] [a/LINK_ADDRESS] [mod/ASSOCIATED_MODULE_NAME]), the UG went on to elaborate that at least one of the optional fields must be provided. This goes against the user expectation.

If a user does not refer to the specific documentation under this part and decide to look at the "Command Summary" section instead, he/she will be confused as why editLink 1 will throw the error At least one field to edit must be provided.,

I do feel that the command format here can be more standardised.

[nus-pe-bot]

Team's Response

While at least one of the edit fields must be provided, we cannot know in advance which one the user wants to edit, thus we cannot indicate any particular field in the "Format" section as being not optional. Otherwise, the user gets the idea that this particular field is compulsory, while in fact it can be omitted in place of another edit field.

The original AB3 UG also writes the "edit" command format in this way, where all fields are marked as optional.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

• [x] I disagree

Reason for disagreement: I would like to raise three points against the team's rejection.

1. If the team already expects the normal non-technical user to understand the "CS"-definition of OR, as indicated in the UG for findLink, then a much better way to standardise the command would be editLink INDEX [n/NAME] OR [a/LINK_ADDRESS] or something of that sort.

2. "The original AB3 UG also writes the "edit" command format in this way." It is indicated in the textbook that "bugs inherited from AB3" needs to be fixed. The excuse here is simply not valid.

3. I do think that the bug description fits the veryLow severity.

---