Repeated prefixes under "Command Parameters" in User Guide is confusing

[Decaxical]

Showing the same prefixes with different meanings is confusing for the User. It would be better to separate the section in different portions like "Command for Students" and "Command for Assessments" etc.

Some examples of repeated prefixes are: ACADEMIC_YEAR and ASSESSMENT_INDEX, MODULE_NAME and NAME, CLASS_GROUP_INDEX and MODULE_CODE

[nus-se-bot]

Team's Response

The table serves as a summary of all the parameters used, and since some parameters are used in multiple commands, it may be more confusing for the user if we have the same parameters over different commands and defeats the purpose of having a summary table.

The 'Original' Bug

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

Multiple identical prefixes are very confusing

I had a lot of struggles reading the User Guide. As we read in order, I am immediately met with an overwhelming long table which has several non-unique prefixes and their special uses (with specific commands) has not been communicated well.

Examples:

3 instances of "n/"

2 instances of "id/"

When do I use student id and when do I use module Id? This hasn't been made clear early enough- should have happened in this table itself with command use examples.

being places as feature flaw due to website stating "Features that work as specified by the UG but should have been designed to work differently (from the end-user's point of view) fall in this category too."

---

_{[original: nus-cs2103-AY2122S2/pe-interim#3398] [original labels: severity.Low type.FeatureFlaw]}

Their Response to the 'Original' Bug

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

While there are identical prefixes, each prefix is only used once for each command. We choose to have identical prefixes as it would make more sense to the reader. E.g. when creating names, it will be more convenient for the user to type add assessment n/... compared to add assessment an/... Having different prefixes may end up confusing the user further. For user-friendliness, we decided to place this table ahead of the commands so as to ensure there is no forward referencing.

Items for the Tester to Verify

❓ Issue duplicate status

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

• I disagree

Reason for disagreement: [replace this with your explanation]

---

❓ Issue response

Team chose [response.Rejected]

• I disagree

Reason for disagreement: I believe that there is a better way to structure the prefix table so that readers have an easier time understanding the prefix table. By structuring the prefix table by headers such as "Prefixes that manage students" and "Prefixes for assessments" I believe that the prefix summary will look neater and more understandable as compared to the current iteration of the prefix table where a bunch of non-unique prefixes are listed. There could even be a general section for commonly used prefixes across the commands if there is a concern that repeating common parameters might cause confusion. My suggestion is just that, a suggestion I am not saying that the team should have adopted such an approach but rather suggesting other ways the team could have structured the prefix table to make it more understandable for the reader.

Thus, I believe that this is a valid documentation bug as it causes confusion for the user and could have been communicated better.

---

❓ Issue type

Team chose [type.FeatureFlaw]
Originally [type.DocumentationBug]

• I disagree

Reason for disagreement: Not sure why this is a FeatureFlaw when the problem lies with how the team decided to structure the prefix table in the UG. I do not see the usage of the same prefix across different commands as a problem but rather how the prefix table is structured in the UG.

---

❓ Issue severity

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

• I disagree

Reason for disagreement: I disagree with the severity change to VeryLow because it is not just a cosmetic problem it actually causes confusion such as myself who read it for the first time thus making it inconvenient.

---