search

lulucopter / pe

0 stars 0 forks source link

UG: Find command `exam_name` is unclear #8

Open lulucopter opened 2 years ago

lulucopter commented 2 years ago

image.png

The specified exam_name does not have any example, samples or any references to what it's values could be.

Users have to scroll down and up into other commands to decipher what is could mean, such as parameters (which I do not think references the same thing)

image.png

or its associated prefixes (which are not the same thing as well)

image.png

This definitely confused me as a user which I was testing the functionality of this application, and was unable to search by exam_name. Without clarification of this in the UG, I wasn't sure if this bug was caused by a functionalitybug or simply because I misunderstood what values exam_name can take. Hence, this should be a documentation bug of severity high. Other users will definitely face the same issue when reading up on this command.

nus-se-bot commented 2 years ago

Team's Response

Although this is a valid issue we do not think this warrants a high rating as the glossary has all the examination names as well. The problem can be that they were not linked with a hyperlink which is acceptable. Moreover, the target audience for this user guide are CS1101S tutors who are well aware of the exam names as they are all briefed before becoming TA's and they have taken the module before. Furthermore, the exam names are written in the GUI of FRIDAY as shown below.

image.png

Furthermore, we believe the name exam_name will clearly refer to the names of exams and nothing else. The use of prefix would have warranted the use of parameter exam_prefix. It does not break the application hence it definitely not a high rating.

Items for the Tester to Verify

:question: Issue severity

Team chose [severity.Medium] Originally [severity.High]

Reason for disagreement: Given that this issue is the same issue that is duplicated from the system test, the unclear documentation of the command made the command unusable, and it repeatedly showed negative results even though I attempted all the different "formats" of what exam_name could be based on the UG. Namely, find ft:100 (the prefix for final score as stated in the UG) and find FINALS_SCORE:100 (The parameter name for final score in the UG).

The explanation of CS1101S tutors knowing what the exams are, are irrelevant to the command use, as this is an issue not with the exam meaning/names itself, but rather how the exam's name is represented and accepted by the application. Your explanation is unclear as well, so do I use the command find Final:100 (Since this is the name in the glossary)? Or do I use find Finals:100 (The name in the GUI)? I still do not know which is the right one to use.

I went back to try again, and realised that using find Final:100, the exam name in the glossary, still doesn't work.. Only after trying again now the name in the GUI (Finals), does the command work.

In fact, if not for your explanation, I would have thought that the command functionality was broken! No error message for thrown for invalid formats, and trying the values given in the UG gives invalid results. Only after your unclear explanation AND with even more guess and checking, do I figure out what's the correct "format". Although it may seen to be a minor "naming" issue, I still believe that this affects the functionality severely as a DocumentationBug, from its' initial FunctionalityBug (Its duplicate)

Hence, although I would say that although the severity lies somewhere in-between medium and high, it still leans towards high since if users never figured out the right syntax for it, they would never be able to search by exam name. Definitely more than an occasional inconvenience, and breaks the functionality and usability all together.