Have more expected outcomes in UG

[tiffanyliu0220]

Some features such as results, topics, solutions, etc. do not have expected outcomes in UG. Perhaps it'd be good to have them in the UG as well as it'd be less confusing for the users who are using the app and for them to know what to expect from the inputs.

[nus-pe-bot]

Team's Response

Thanks for your bug report!

We are unclear what you meant by "expected outcomes in UG".

Here, we assume "expected outcomes" mean "sample outputs", like so:

Sample output for topic (UG page 4):

If so, we have 1 main reason why we did not include sample outputs for results and solution.

1. The descriptions of these features are considered to be sufficient for understanding.

Hence, for these features, sample outputs are trivial since it is not a requirement to include them in the UG (similar to how we omit getter and setters in class diagrams)

Description of results Feature:

Description of solution Feature:

As seen from the descriptions above, results and solution only serve as the "getters" for results and solutions respectively, so it should be intuitive the commands will display the results/ solutions (i.e expected outputs).

This is in comparison to more complicated/ unique features like timed mode, whereby the description may be insufficient to convey fully what the feature does, and where the sample output may not be intuitive (i.e. try to imagine what you would see if you "have entered timed mode" vs "the solution will be displayed")

Description of timed mode Feature (UG page 5)

Sample Output of timed mode

In addition, note the textbook's deliverables for UG:

The 'Original' Bug

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

No sample output for many functions in user guide

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.

---

Many of the functions in the user guide does not have a sample output. Would be good to have sample output to indicate to user what they are supposed to see if they are using the program correctly.

---

_{[original: nus-cs2113-AY2324S2/pe-interim#659] [original labels: type.DocumentationBug severity.VeryLow]}

Their Response to the 'Original' Bug

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

Thanks for your bug report!

We have 1 main reason why we did not include sample outputs for results and solution.

1. The descriptions of these features are considered to be sufficient for understanding.

Hence, for these features, sample outputs are trivial since it is not a requirement to include them in the UG (similar to how we omit getter and setters in class diagrams)

Description of results Feature:

Description of solution Feature:

As seen from the descriptions above, results and solution only serve as the "getters" for results and solutions respectively, so it should be intuitive the commands will display the results/ solutions (i.e expected outputs).

This is in comparison to more complicated/ unique features like timed mode, whereby the description may be insufficient to convey fully what the feature does, and where the sample output may not be intuitive (i.e. try to imagine what you would see if you "have entered timed mode" vs "the solution will be displayed")

Description of timed mode Feature (UG page 5)

Sample Output of timed mode

In addition, note the textbook's deliverables for UG:

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.NotInScope`] - [x] I disagree **Reason for disagreement:** As mentioned in another bug issue, on the documentation bug where the UG should specify and emphasise more on how the results are viewed in the order of the total number of attempts, from there, I was confused as to the output of the results as by intuition, I thought that the results were categorised into different topics and thus the number of attempts that you have mentioned in the UG under the results section would mean the number of attempted made under each topic (eg under topic 1, attempt 1: results ... attempt 2: .....), instead of the total number of attempts (which is what you intended). Hence, from there I was not sure about whether the output I got was the expected output and I could not refer to anything to confirm as the UG did not contain expected sample outputs, nor did it specify that it's the total number of attempts irregardless of which topic we have attempted. Hence, from there the sample expected output became more crucial in guiding and aiding the users on how the app works and what they're supposed to be seeing, especially when this case is less intuitional and more unusual as compared to usual results format (sorting by topic, then by the number of attempts of that topic, instead of total attempts of all topics together).

---

## :question: Issue severity Team chose [`severity.VeryLow`] Originally [`severity.Medium`] - [x] I disagree **Reason for disagreement:** Perhaps not of medium severity, but I think it should be severity.Low at least.

---