search

rageqqq / pe

0 stars 0 forks source link

Clearer information can be provided about whether an argument is compulsory or optional #12

Open rageqqq opened 3 years ago

rageqqq commented 3 years ago

image.png

The UG states that the lesson type for the "add lsn" command cannot be skipped. However, all the arguments are shown in the <> brackets. This can make it difficult for a user to know whether an argument is compulsory. One suggestion can be using different brackets to help users distinguish between compulsory and optional arguments

nus-pe-bot commented 3 years ago

Team's Response

In the tips section below, we mentioned that the "lesson type" cannot be skipped, while the others can be skipped.

If you are coming from the point that it can be made easier to read, this is subjective so we think this seems to be a suggestion and not a bug?

From our point of view, adding it to the format may lead to some users misinterpreting what it means to be optional, and end up inputting the command wrongly. Hence, we only have it in the tips section so that only readers who pay more attention and are more familiar with the product would use it. Being able to skip is a bonus trick for advanced users rather than something essential to the command.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: There is no suggestion bug type so I have to put it as a documentation bug. I feel like it is quite straightforward to include that [] is for inputs that cannot be skipped, while say <> can be for optional things. Since you have multiple commands with similar structure it can help make the guide easier to read. The different types of brackets can then be mentioned in "How to use this guide" portion.

:question: Issue severity

Team chose [severity.Low] Originally [severity.Medium]

Reason for disagreement: [replace this with your explanation]