search

Kair0s3 / pe

0 stars 0 forks source link

UG for `suggest` may be confusing in terms of the possible output variations. #11

Open Kair0s3 opened 2 years ago

Kair0s3 commented 2 years ago

Since, the output images may vary depending on the reader's configurations of the values, perhaps a note letting the reader know that this is just a sample list and not a standardized suggestion list would be nice.

This is in case that if the reader is a user as well and when trying to list the suggested foods, may get confused since they may get an entirely different list of suggestions - especially if they did not follow some sort of sequence when trying out the features.

eg. The UG

image.png

vs eg. My side

image.png

soc-se-bot commented 2 years ago

Team's Response

It does not make sense to force all users to configure their FoodDatabase such that their suggestions will match those given in the user guide. As for your remark "note letting the reader know that this is just a sample list", this is already clearly stated right above the images Sample output:. Furthermore, suggestions also depend on numerous factors such as calories consumed so far today, calorie goal of the user, etc. Therefore, it is impossible to guarantee that all users have the same/similar suggestions as compared to the user guide. Additionally, the number of matching suggestions given in the example from the user guide is deliberately limited in order to improve readability for the reader.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: I do agree with you that it makes no sense to force all users to configure the FoodDatabase based on a very specific "setup" which would go against the main feature of this application as well as the viewpoint that reducing the number suggestions does improve readability.

However, I believe that my main argument is the ambiguity of what this sample output is.

And let me explain what I mean, because based on the other "Sample outputs:" through UG, there are some of those with standardized expected outputs (e.g. age /set 18, height /set 18) while some are deterministic depending on the user's configuration (e.g. suggest /meal). Thus users who are learning the program while referring to the UG, may not know which of the sample outputs can be used to check word for word whether their "command" has worked properly or not, since some are deterministic output images while some are more fixed and predictable.

To summarise, there is not much information given to the reader to know which output images shown are deterministic and what isn't (although from developer's POV this seems to be common sense). And this was also the reason for my remark, to in some way let readers know that some outputs are deterministic or not to reduce ambiguity for the readers (also could be users in this case).