search

narwhalsilent / pe

0 stars 0 forks source link

Inconsistent syntax for command parameters in UG #5

Open narwhalsilent opened 6 months ago

narwhalsilent commented 6 months ago

In command syntax, the parameter values are represented as (something).

image.png

However, when giving tips, the brackets are not kept, and the name of the parameters are changed. e.g. (id) to ID and (handphone) to phone number.

image.png

This can confuse the reader.

Improvement: Standardise how parameters are referred to in UG.

nus-se-script commented 5 months ago

Team's Response

We believe that this is a cosmetic issue as there is no obvious problems when reading through.

e.g There should be no problem reading id then ID. We also mention this in this section of the UG. handphone and phone number are used interchangeably in real life, so there is no problem there as well. We are not using like office number and phone number separately.

image.png

image.png

Items for the Tester to Verify

:question: Issue response

Team chose [response.NotInScope]

Reason for disagreement: I believe that it is essential to have a consistent format when referring to command syntax and parameters, because command syntax cannot be read like natural speech.

Instead, command parameters are in effect treated like special symbols which are unique and have no equivalents.

The group's UG also shows the team intended to refer to parameters with the exact same format as shown in command format, i.e. lowercase with brackets. In the following screenshot, it is exemplified by the phrase "(id) is the parameter to be supplied by you".

image.png

Hence, in the screenshot in the original bug report when the team refers to "ID", it could have been confusing as it is a different convention for the syntax of parameters.

I believe it would have been much more easily readable if the team stuck to this convention.

## :question: Issue severity Team chose [`severity.VeryLow`] Originally [`severity.Low`] - [x] I disagree **Reason for disagreement:** I believe that this is not a purely cosmetic or grammatical issue. In particular, it impedes understanding. his is because words marked out by the backtick syntax cannot be understood as natural speech. They are regarded to have special syntactical meaning, and any difference in spelling, capitalisation etc could signal to the reader that it is referring to a different parameter.