missing update feature explanation in DG

[NeoHW]

missing update feature explanation in DG

Preview

Developers who use developer guide will not know about

• existence of the update feature,
• how it is implemented
• logic

[soc-se-bot]

Team's Response

We agree that the exclusion of a feature may hinder the ability for developers to fully understand our implementations. However, we feel that there is currently enough information in our DG for developers.

The screenshot below is taken from our DG.

In our DG, we have included a sequence diagram of executing a delete command. The update command follows a similar logic.

Moreover, it is not stated in the tP requirements that there needs to be a comprehensive writeup on the implementations of all of our features.

We have incorporated comprehensive guides on the implementations of our more complex and heavy features such as undo/redo, and display. And features that do not get a thorough deep dive, usually are similar to other features that are explained (such as delete in the above example). Therefore, we think that this issue only is a minor inconvenience to users and therefore should be regarded as low severity.

We also think that as we already have enough content in the DG, we think that fixing it is less important than the work done in the current version of the product. Therefore, we believe this bug to be not in scope, as it could be an extension for further clarity, but we do think we have sufficient clarity for users.

The 'Original' Bug

[The team marked this bug as a duplicate of the following bug]

missing Add feature explanation in DG

Note from the teaching team: This bug was reported during the Part II (Evaluating Documents) stage of the PE. You may reject this bug if it is not related to the quality of documentation.

---

Developers who use developer guide will not know about

• existence of the add feature,
• how it is implemented
• logic

---

_{[original: nus-cs2103-AY2324S2/pe-interim#885] [original labels: severity.Medium type.DocumentationBug]}

Their Response to the 'Original' Bug

[This is the team's response to the above 'original' bug]

We agree that the exclusion of a feature may hinder the ability for developers to fully understand our implementations. However, we feel that there is currently enough information in our DG for developers.

The screenshot below is taken from our DG.

In our DG, we have included a sequence diagram of executing a delete command. The add command follows a similar logic.

Moreover, it is not stated in the tP requirements that there needs to be a comprehensive writeup on the implementations of all of our features.

We have incorporated comprehensive guides on the implementations of our more complex and heavy features such as undo/redo, and display. And features that do not get a thorough deep dive, usually are similar to other features that are explained (such as delete in the above example). Therefore, we think that this issue only is a minor inconvenience to users and therefore should be regarded as low severity.

We also think that as we already have enough content in the DG, we think that fixing it is less important than the work done in the current version of the product. Therefore, we believe this bug to be not in scope, as it could be an extension for further clarity, but we do think we have sufficient clarity for users.

Items for the Tester to Verify

:question: Issue duplicate status

Team chose to mark this issue as a duplicate of another issue (as explained in the Team's response above)

• [x] I disagree

Reason for disagreement:

1. One is update feature, and one is a add feature
2. Adding in an add section in the DG does not automatically fix the missing update section in the DG.

---

## :question: Issue response Team chose [`response.NotInScope`] - [x] I disagree **Reason for disagreement:**  * This is clearly a documentation issue and not a flaw (e.g. missing feature, suboptimal design, known bug). Furthermore, none of the condition are fulfilled for it to be a NotInScope. * There was no mention that the command was intentionally omitted/coming in future or similar to other commands.

---

## :question: Issue severity Team chose [`severity.Low`] Originally [`severity.Medium`] - [x] I disagree **Reason for disagreement:** The argument provided by the team, while acknowledging the potential hindrance caused by excluding the update feature explanation, falls short in addressing the fundamental purpose of documentation. It's essential to recognize that documentation serves not only the immediate needs of current developers but also future developers who may join the project. By omitting a mention or basic explanation of the update feature, the documentation fails to fulfil its role as a comprehensive reference for understanding the system's functionality. > Moreover, it is not stated in the tP requirements that there needs to be a comprehensive writeup on the implementations of all of our features. The point in note suggests that there need not be very comprehensive writeup on **all** features, but it's crucial to ensure that essential features are adequately documented to prevent confusion and facilitate efficient development and maintenance. Even a brief mention or overview of the update feature's existence and basic logic would significantly enhance the DG's value by providing clarity and context to developers, both present and future. Additionally, dismissing the issue as a minor inconvenience overlooks the potential consequences of incomplete documentation. Without clear documentation on the update feature, developers may waste time and effort trying to understand its implementation, leading to delays and inefficiencies in the development process. Moreover, neglecting to address documentation deficiencies undermines the overall quality and professionalism of the project, potentially eroding trust and confidence in the team's capabilities. Since it is **omitted entirely**, it is definitely not a minor flaw and would definitely cause inconvenience for most users reading the DG, even more so since the `update` command is one of the main commands and functionalities. There was also no mention that the command was intentionally omitted/coming in future or similar to other commands.

---