alvinlim277 / pe

0 stars 0 forks source link

Slightly confusing formatting when introducing command syntax #9

Open alvinlim277 opened 7 months ago

alvinlim277 commented 7 months ago

The bright orange header for each command introduction section introduces the command format which differs from the actual command syntax. In the example below, add [index] [fields] grabs more attention than add [index] [field prefix] [field value] which causes minor confusion especially if the user is just making a quick glance at the UG to refer. It might be better to have the heading match the actual command syntax as well.

image.png

nus-pe-bot commented 7 months ago

Team's Response

It can be interpreted as fields being a combination of field prefix and field value, furthermore, the header is formatted in such way to conform to the command summary format. If we make the headers explicit, the header would be too long, hindering the readability. Note that not all fields are compulsory, so listing out all possible fields in the header would cause more confusion. Furthermore, there are examples below to illustrate the usage, so there is no ambiguity.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: [replace this with your explanation]