nus-pe-script
commented
2 years ago Team's Response
No details provided by team.
The 'Original' Bug
[The team marked this bug as a duplicate of the following bug]
Lack of examples for edit feature
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.
In this case, for an extremely crucial feature such as this, I think it makes sense to include perhaps one or two more examples. My reasoning is that due to the complex nature of this command (a lot of parameters and spaces to follow) it is quite possible for the user to make mistakes when they try it out. So, examples will go a long way in improving their experience.
[original: nus-cs2113-AY2122S1/pe-interim#672] [original labels: severity.Medium type.DocumentationBug]
Their Response to the 'Original' Bug
[This is the team's response to the above 'original' bug]
I think this is very subjective.
This line clearly explains the order for formatting.
These lines shows that it is possible to do 1 parameter only
These show that it is possible to do 2 parameters with order.
Reason as to why not more was added for 2, was that following the above examples, it is easy to understand how a command should be. More examples would make the already length format subsection more lengthy and would not add much value to it overall.
Reason for choosing that specific 2 parameter example, the /from parameter would be the least used example as it is a high chance to be your home country, thus the 2 most used parameters were chosen instead.
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)
- [ ] I disagree
Reason for disagreement: [replace this with your explanation]
:question: Issue response
Team chose [response.Rejected]
- [x] I disagree
Reason for disagreement: I believe this problem is quite self-explanatory and yet again, just because you can understand it just fine, doesn't mean everyone else is blessed with such clairvoyance. This problem is clearly cited under UG documentation bugs as shown in the module website:
For the screenshot below, this bug is related to the first bullet point and the last two:
:question: Issue severity
Team chose [severity.Low]
Originally [severity.Medium]
- [ ] I disagree
Reason for disagreement: [replace this with your explanation]
Although it is possible to understand them after a bit of reading, I feel like it can still be a bit difficult for most others. Instead of clumping all the commands and their examples into separate sections, it is better to talk through one command at a time and follow up with an example showing it's working. Otherwise, users will have to move back and forth and might have trouble associating the correct command with the expected output.