Incorrect notation for compulsory parameters in UG

[Joellimjr]

Compulsory parameters should be just in uppercase letters. The [ ] around the parameters implies that they are optional but they are actually compulsory.

[soc-pe-bot]

Team's Response

While we acknowledge that there are different conventional formats for denoting compulsory parameters, it's important to note that there is no universally accepted standard across all documentation or development practices. Different teams and organizations may adopt slightly different conventions based on their specific needs and preferences.

In our case, we opted for a format that prioritizes clarity and ease of understanding within the context of our course materials and command environment. Our decision to enclose parameters in square brackets, regardless of their compulsory status, was made to ensure consistency and readability, especially in a case-insensitive environment where differentiation between commands and parameters is important.

Moreover, since this is just a summary, our approach is aligned with the principle of maintaining a user-friendly experience, as it helps users quickly identify the parameters for each command without the need for additional memorization or interpretation of what the presence or absence of square brackets could mean. To gather more details, we suggest to refer to the command guides themselves.

To bring across our point of the existence of different formats, please refer below for different formats commonly used:

1. Positional Order: Parameters might be listed in a specific order, with compulsory parameters listed before optional ones. Users are expected to provide compulsory parameters in the specified order, while optional parameters can be provided in any order or omitted entirely.
2. Explicit Labels: Compulsory parameters are often explicitly labeled as required, mandatory, or compulsory, while optional parameters might be indicated as optional or have no specific label.
3. Brackets or Braces: "square brackets [ ]", curly braces "{ }", or angle brackets "< >" might be used to enclose optional parameters, while compulsory parameters are listed without any enclosing symbols.
4. Documentation: Clear documentation accompanying the command or function typically specifies which parameters are required and which are optional. This can include descriptions, usage examples, or syntax diagrams.
5. And many many more...

Lastly, within the context of this course, we wish to iterate again that the example given in the AB3 UG (NOT explicitly made compulsory to follow) is just one of the many conventions and that different teams may have slight variations depending on their own considerations (we used number 4). And just FYI, using capitalized lettering for parameters as shown in the AB3 UG is also not universally accepted.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

• [ ] I disagree

Reason for disagreement: [replace this with your explanation]

---