No diagram given in UG to help user

[m1oojv]

this is also inconsistent of other commands that gave a diagram

[nus-se-bot]

Team's Response

Under User Guide in tP: Deliverables, it is specifically stated for us to not use excessive screenshots:

The screenshots are simply to provide some idea of what the user can expect to see when they execute the commands, and if it is added for every single command then a lot of the screenshots will simply be duplicates of each other.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

• [x] I disagree

Reason for disagreement: Dear Team,

I appreciate your commitment to adhering to the guidelines regarding the use of screenshots in the User Guide. However, I'd like to highlight the importance of visual aids in enhancing user understanding, particularly for commands that are complex or have significant visual outcomes. While it's crucial to avoid redundancy, it's equally important to ensure that users have all the necessary tools to understand and effectively use our application.

1. Value of Visual Aids: Diagrams and screenshots play a pivotal role in helping users grasp the functionality of an application, especially for those who are visual learners or new to the software. For certain commands, textual descriptions alone may not sufficiently convey the outcome or the steps involved.

2. Balancing Redundancy and Clarity: While the concern about avoiding excessive screenshots is valid, the absence of visual aids for certain commands might lead to gaps in understanding. It's important to strike a balance—ensuring that visual aids are provided for commands where they can significantly aid comprehension, even if this means slightly increasing the number of screenshots or diagrams.

Without relevant screenshots, this hinders the user in using your user guide effectively as "it can slow down the reader or require the reader to put more effort than necessary" into reading or using your user guide

3. Consistency in Documentation: The inconsistency in the provision of diagrams for different commands can be confusing for users. If some commands are accompanied by visual aids and others are not, users might wonder about the reasoning behind this discrepancy. Ensuring a more uniform approach to visual aids can enhance the overall coherence and user-friendliness of the guide.

4. Enhancing User Experience: Our goal should be to make the User Guide as intuitive and helpful as possible. Including diagrams for commands that would benefit from visual representation can greatly improve the user experience, making it easier for users to understand and apply the instructions.

Given these considerations, I propose revisiting the sections of the User Guide where diagrams are currently missing, especially for commands that are complex or visually impactful. This would not only align with best practices in documentation but also enhance the usability and effectiveness of the guide.

Additionally, I'd like to highlight the guidance provided by the professor regarding the handling of bugs. A rejection of a bug should be reserved for cases where the bug is deemed irrelevant or unnecessary to address, both in the current context and in the foreseeable future. However, in this instance, the issue at hand is directly relevant and necessary to address. The absence of clear, focused screenshots in the User Guide can lead to confusion and diminish the effectiveness of the documentation. This issue is particularly relevant given the module's emphasis on adhering to high standards of documentation, as exemplified by the Google developers documentation standards.

The provision of screenshots in a User Guide is not just about visual supplementation but about enhancing the user's understanding and ease of use. Without screenshots, users may struggle to identify the relevant areas or changes resulting from a command, like you justified in this other issue , quoting your justification " the screenshots are simply to provide some idea of what the user can expect to see when they execute the commands ".
Therefore, I think it is agreeable that screenshots are important for the user thus this is a valid documentation bug to be reported.

---

## :question: Issue severity Team chose [`severity.VeryLow`] Originally [`severity.Medium`] - [x] I disagree **Reason for disagreement:** I would like to address the classification of the severity of this issue as 'Very Low.' Considering the target audience and the purpose of these screenshots, this issue goes beyond a cosmetic concern and significantly impacts the usability of the guide, warranting a reclassification to at least 'Medium' severity. 1. Impact on Target Audience: Our primary users, head nurses, are professionals with limited time for learning new software, often needing to access information quickly and efficiently. The lack of clear screenshots adds unnecessary complexity to their learning process. This is not a mere inconvenience but a substantial barrier to effectively understanding and using the application. Without relevant screenshots, this hinders the user in using your user guide effectively as "it can slow down the reader or require the reader to put more effort than necessary" into reading or using your user guide  2. Impact on Understanding Complex Commands: The absence of diagrams for certain commands, particularly those that are complex or have significant visual outcomes, can impede user comprehension. Visual aids are not just an enhancement but can be essential for understanding how to use specific features of the application. 3. Frequency of Impact: This issue is not one that appears in 'very rare situations' but is likely to be encountered by every new user of the application. The current lack of screenshots can cause repeated confusion and slow down the learning process, which is a significant concern in a fast-paced healthcare environment. The lack of diagrams for certain commands could be a frequent obstacle, causing more than just minor inconvenience. This aligns more closely with the definition of 'Medium' severity, as it causes occasional inconvenience that impedes the effective use of the product.  4. Consistency and User Expectation: If some commands in the User Guide are accompanied by diagrams and others are not, it can create inconsistency and confusion. Users might expect a similar level of guidance across all commands, and the absence of diagrams where they are needed can lead to frustration or a steeper learning curve. 5. Enhancing User Experience and Accessibility: The inclusion of diagrams is particularly important for visual learners or users who find textual instructions alone challenging to follow. By providing diagrams where they are most needed, the guide becomes more accessible and user-friendly, enhancing the overall user experience. Given these considerations, the issue of missing diagrams in the User Guide should be viewed as having a more substantial impact on the user experience, warranting a 'Medium' severity classification.

---