Glossary Is Spare

[rui-han-crh]

Description

The UG contains a glossary that is too sparse.

Important terms not familiar to layman like parameters, json, prefixes, pin are not included.

Justification for Severity: Medium

In the worse case, the user does not understand the words. In the best case, the user has to look up online for the definition of words.

[nus-se-script]

Team's Response

Justification for downgrading from severity.Medium to severity.VeryLow:

Based on the above bug report, we do not add too much details for such terms in the glossary because the target audience of TrackAScholar is administrative staffs, which should have a basic grasp of English and have a common understanding for these terms. Furthermore, we do not wish to overwhelm our users with too much explanations in the glossary section.

We do acknowledge that we have certain keywords missing such as json, windows and mac missing from the glossary which people unfamiliar with technical terms might not understand. However, such an issue does not account for a Medium severity as it is not a flaw that affects use of the product. Hence, we justify that this issue has a severity rating of VeryLow since the problem is purely cosmetic and does not affect usage of the product.

Items for the Tester to Verify

:question: Issue severity

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

• [x] I disagree

Reason for disagreement: I'm disagreeing because I don't think this is a purely cosmetic issue with the documentation. I think it is a flaw that may occasionally affect the readability of the documentation.

For example we have functions that will sort the product in lexicographic and reverse-lexicographic order, but the definition of these terms aren't made clear. The user has to google the definition of these words and this takes away from the intention of the UG.

In addition, layman users may not understand the words import or filter, as their definition used in this guide is in the computing terms of "transferring data into a file or document" and "processing some data by removing the unwanted data", but they also have other definitions outside the computing domain. The scope of these words are not defined in this UG and may cause confusion to the reader.

There are more terms with computing definitions like fields, execution (this word is in a picture at the Overview section), parameter, type and prefix which have other definitions in other domains. It can make the User Guide bewildering to read, especially if the administration staff using this application and reading this guide has not seen such words being used in this context before.

In the find section of this UG, the introduction of several technical terms makes the UG really confusing, even for me, and I could not find what terms, like the word type, mean in this context.

I just don't think it's a cosmetic issue, and it can affect the readability of the User Guide to the target audience. It won't overwhelm the users to introduce more clarity in the glossary.

---