Inconsistent headers for command

[m1oojv]

Add affiliation vs Returning affiliation

I do not think its purely cosmetic coz it may make the user think that these commands have their differences

[nus-pe-script]

Team's Response

Not sure what you mean, but they are indeed two distinctly different commands:

• Adding an affiliation for a person uses addaffn command.
• Returning the affiliations of a person, i.e. listing down the affiliations, uses affn command.

  Items for the Tester to Verify

  :question: Issue response

Team chose [response.Rejected]

• [x] I disagree

Reason for disagreement: I appreciate your clarification regarding the distinct functionalities of the 'addaffn' and 'affn' commands. However, my concern lies not with the functionality of the commands themselves, but with the inconsistency in tense used in their headers, which can impact user understanding and perception of these commands.

1. Clarity in Documentation: Consistent tense usage in command headers is crucial for clear and unambiguous documentation. When different tenses are used (e.g., "Add" vs. "Returning"), it can create an impression of inconsistency in the application's interface design. This might lead users to mistakenly believe that the commands are used in fundamentally different ways or contexts.

2. User Perception and Understanding: Consistency in documentation helps in establishing a predictable pattern that users can easily follow. Inconsistent tense usage could potentially confuse users, especially those who are new to the application. They might spend unnecessary time trying to discern non-existent differences between the commands based on the tense used in their headers.

3. Professionalism and Standardization: Adhering to a consistent tense in command headers reflects a level of professionalism and attention to detail in the application's documentation. This is particularly important in a professional setting like healthcare, where clarity and precision in communication are paramount.

4. Enhancing User Experience: Aligning the tense used across all command headers enhances the overall user experience. It contributes to a more intuitive and user-friendly interface, where users can focus on the functionality of the commands without being distracted by inconsistent documentation practices.

Given these points, the issue at hand extends beyond a mere cosmetic concern. It is about ensuring clarity, consistency, and professionalism in the application's documentation, which directly impacts user experience. I recommend revising the command headers to use a consistent tense, thereby enhancing the clarity and usability of the application.

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 of inconsistent tense usage in command headers is relevant and necessary to address for several reasons. The consistency in documentation directly impacts how users interact with and perceive the application. It's not a matter of mere preference but a fundamental aspect of clear and effective communication, especially in a professional setting like healthcare, where precise and unambiguous instructions are crucial. Considering this perspective, the issue should not be dismissed as inconsequential or irrelevant. Instead, it should be acknowledged as a genuine area for improvement, in line with the goal of enhancing user experience and interface intuitiveness.

Additionaly, the module website clearly states for documentation to follow the Google developer documentation guidelines and to be consistent with it. Therefore, this is a significant documentation bug.

---