Missing Glossary Section in UG

[freshcabbage123]

There is no glossary section in UG but there is a glossary section in the DG. Definitions such as integers are important and perhaps should have been clarified within a specialised section as well. Even in this case for definition of positive integer, would the application be able to support numbers greater than MAX_INT? That is an example of an unclear definition as a result of a missing glossary section. It is very inconvenient for users to have to think through all the possible terms used throughout the user guide as such Medium.

Another example is the italicising of home folder but not defined why is it italicised in the Quick Start section

[nus-se-script]

Team's Response

There are 2 bugs reported in the bug report.

Bug 1: The italicising of the home folder.

This bug is treated as having lower severity as it does not hinder the user in any way and does not seem to be the main issue addressed. Therefore, we will be responding to bug 2.

Bug 2: The lack of proper definition of "positive integer".

As shown above, positive integer is defined for the user "(i.e. 1, 2, 3...)". It would not be realistic for a user to have 2^31 contacts in the AddressBook and as such, it is not mentioned in the UG. Regardless, trying to input a large number above MAX_INT will cause an error message to be displayed that indicates that numbers above this limit are not accepted. This is not shown in the UG as we believe it to be a constraint of the programming language that should not be exposed to the user.

Furthermore, to supplement the above-mentioned case where definitions are defined where the terms are used, we have also embedded definitions of the terms we have used in sections of the UG where they are relevant throughout multiple sections, as seen in the examples below.

Event and Task definitions:

Event Span and Date time format definitions:

As for the lack of a dedicated glossary section, we appreciate the suggestion and will consider adding it to consolidate the terms used for extra clarity in the future.

Items for the Tester to Verify

:question: Issue response

Team chose [response.NotInScope]

• [x] I disagree

Reason for disagreement: I disagree with the assessment that the issue of missing glossary terms is out of the scope for the user guide (UG). On the contrary, it is an essential element within the scope of documentation, particularly for an application intended for users of varying backgrounds and expertise levels.

The existence of a glossary in the developer guide (DG) acknowledges the necessity of such definitions for understanding application-specific jargon. Excluding the glossary from the UG overlooks the needs of the end-user, who may not have the same technical background as developers but requires the same level of understanding to operate the application effectively.

Adding a glossary is a practical solution that serves as a reference point for users to quickly understand essential terms and concepts, thus enhancing the user experience. It ensures that the application is inclusive and user-friendly, catering to all students, not just those with a computing background. The omission of a glossary could lead to confusion, misinterpretation of functionality, and an overall decrease in the application's usability.

Furthermore, the lack of clarity and consistency in formatting choices, such as italicization, can create an inconsistent narrative that hinders the user's ability to follow and comprehend the UG. The application team should consider implementing a glossary and reviewing the UG for consistent formatting to improve user comprehension and reduce potential inconvenience. Therefore, this issue is very much within the scope and should be prioritized accordingly to reflect its impact on the user experience.

---

## :question: Issue severity Team chose [`severity.VeryLow`] Originally [`severity.Medium`] - [x] I disagree **Reason for disagreement:** I appreciate your perspective on the issue's priority, but I'd like to clarify why the absence of a comprehensive glossary and undefined terms in the user guide (UG) significantly impacts the usability of the application, particularly for a diverse user base. 1. Broad User Base Consideration: The UG is designed for all students, including those in primary school and those without a computing background. Terms like 'index' and 'ASCII', while familiar to a more technically inclined audience, can be perplexing to others. A lack of understanding of these terms can hinder the user's ability to effectively utilize the application. 2. User Experience and Accessibility: A key aspect of user experience is ensuring that information is accessible and comprehensible to all users. The absence of definitions or a glossary for critical terms can lead to confusion, significantly diminishing the usability of the application. This is not just a cosmetic issue; it directly impacts the functionality and user satisfaction. 3. Consistency in Presentation: The inconsistent use of formatting, like the italicization of the home folder without explanation, can confuse users. Consistency in how information is presented aids in user comprehension. If there's a stylistic choice (such as italicization), it should be accompanied by a rationale or guideline within the UG to avoid misinterpretation. The explanation for italicised terms can be done so in glossary, which was the intention of the original issue. 4. Educational Responsibility: Given that the application targets students, it holds an educational responsibility to clarify and educate its users about terms and concepts used within the application. This is crucial for facilitating learning and ensuring the application is a valuable educational tool. 5. Potential Solutions: To address this, a dedicated glossary section could be implemented in the UG, providing clear and concise definitions of technical terms. Additionally, a review of the UG to identify and define jargon, technical terms, and any formatting styles would greatly enhance user comprehension and experience. In summary, the issue extends beyond a mere cosmetic flaw. It's about ensuring the application is user-friendly, accessible, and educational for all its intended users, regardless of their prior knowledge or background. Addressing this issue should be considered a medium to high priority to enhance the overall effectiveness and usability of the application. 

---