nus-se-bot
commented
10 months ago Team's Response
Our team has noticed that some quick reader of UG may not understand our design and be confused by the scenario mentioned above. Thus, we have specifically mentioned in FAQ the reason behind it and how could user solve this problem:
Q: After I reviewed a flash card, I edited details of the card by the edit command. Will I be able to see these changes immediately reflected in the review session?
We've also highlighted the level updating mechanism at the very beginning of UG in application feature:
The level of the flash card will be updated after each review session.
Since we want to follow the same format in command section, we provide basic, necessary command format and expected output. It is a place to introduce the command, whereas FAQ is a more suitable place to address user's questions.
Level of this issue has changed to low since FAQ has displayed the "missing information" very clearly and "it's unlikely to affect normal operations of the product."
Items for the Tester to Verify
:question: Issue response
Team chose [response.Rejected]
- [x] I disagree
Reason for disagreement: As already mentioned in the original bug report, a user might not know of this intricacy. As such, "they will refer to the edit section", and not the FAQ section. It is also acknowledged by the team that a quick reader of the UG may be confused. A quick reader might go straight to edit instead of going through the entire documentation to find that in the FAQ. While I am not disputing that it is good to have it in the FAQ as well, the point of the bug report is that this information should be specified in the edit section, as it is directly related to this command.
Once again, their second point mentioned that the mechanism is highlighted at the "very beginning of the UG". As mentioned yet again. a quick reader would not spend the time to read the entire UG and remember what they read. It is essential that the critical information, such as the ones relating to each feature, be put together in the same section, rather than 1 at the beginning, and another at the FAQ, which is at the bottom, while the feature explanation itself is in the middle.
This messy structure of the documentation, all to answer this 1 concern is the precise reason why I pointed it out as a bug. I argue that this bug should not be rejected as in the real world, companies cannot possibly rely on users to comb through the documentation to find the answer to 1 question. The structure makes it confusing to understand, and thus as per the course website, this counts as a documentation bug.
Furthermore, their argument that they did not include the information in the command section because they wanted to standardise formatting does not seem to be a strong nor valid reason. In the real world, it is essential to prioritise clarity and user friendliness, over format standardisation (at the expense of clarity). Their reasoning implies that users should look at the FAQ for every question that they have regarding the commands. In this scenario, their FAQ might have over 100 questions. Their notes section in each feature is precisely to make the feature clear so that users questions can be answered as they are reading more about the feature. It does not stand to reason that some answers are included in the feature, and some is left to the FAQ. Their FAQ is not categorised by command either. To find an answer regarding Edit, I would likely have to comb through all the FAQs to then find the answer to my question about the edit command.
In short, FAQs are to address questions about the product in general, things that do not lie in any particular category, and users would intuitively go there to source for answers. If it is a clarification regarding command, it would be more intuitive, and thus logical that the information be put in the command section.
## :question: Issue severity Team chose [`severity.Low`] Originally [`severity.Medium`] - [x] I disagree **Reason for disagreement:** Their argument for changing the severity is just quoting the course website without explaining why its "unlikely to affect normal operations". As seen here, severity.Low means "A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.". I would think that this Q&A is a common concern users have (which is their reasoning for including it in the FAQ only.) . Thus it does not just appear in very rare situations. It did in fact affect my operations because it was after editing the meaning, and searching through the documentation, did I realise I cannot actually reset the level. If I had realised this earlier before the edit command, I might have proceeded to add a new word instead so that the level can be reset to 0. But I can still continue to use the product and therefore it is only of medium and not high severity. 
As a user that is not familiar with your documentation, I may not know that even after editing the translation, I am unable to review again until the next calculated interval. As such I will refer to the edit section. Would be good to specify this information that a user cannot review the same word even after editing.