search

ivanaitzliddat / pe

0 stars 0 forks source link

Inconsistent syntax in command summary #30

Open ivanaitzliddat opened 2 years ago

ivanaitzliddat commented 2 years ago

Perhaps, <index> in module can be replaced with INDEX, given that the others are INDEX

image.png

soc-se-bot commented 2 years ago

Team's Response

This essentially gets at the same issue as #844, where the formatting of command arguments is slightly different across components.

The 'Original' Bug

[The team marked this bug as a duplicate of the following bug]

Inconsistent formatting

Note from the teaching team: This bug was reported during the Part II (Evaluating Documents) stage of the PE. You may reject this bug if it is not related to the quality of documentation.

The format of the commands are inconsistent across different features. Unsure if those between &lt and &gt are optional or no difference.

image.png

image.png

[original: nus-cs2113-AY2122S2/pe-interim#1026] [original labels: type.DocumentationBug severity.VeryLow]

Their Response to the 'Original' Bug

[This is the team's response to the above 'original' bug]

While it is true that each section has a slightly different format to denote expected parameters, they have been further clarified in their respective sections by providing relevant examples to avoid any confusions. As such they do not hinder the reader in anyway as the formatting is purely cosmetic in nature. This is therefore not in the current scope of our application. We will take this suggestion as a possible improvement for future versions.

Items for the Tester to Verify

:question: Issue duplicate status

Team chose to mark this issue as a duplicate of another issue (as explained in the Team's response above)

Reason for disagreement: [replace this with your explanation]

:question: Issue response

Team chose [response.NotInScope]

Reason for disagreement: This cannot be rejected as not in scope. This is a feature that is supposed to use now. Examples are indeed provided but this may still hinder the understanding of some users, especially if it does not clearly state if one is optional or not.

I could possibly have a command for my application that has optional arguments but provide an example with all the arguments given. Without these proper formatting, the user will not be able to catch if the arguments are supposed to be optional or not.