soc-pe-bot
commented
4 months ago Team's Response
No details provided by team.
The 'Original' Bug
[The team marked this bug as a duplicate of the following bug]
Insufficient diagram for implementation 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.
The implementation is too wordy and do not have diagrams to support which makes it hard to read and understand. It will be good to add more diagram, e.g. activity diagram, sequence diagram.
[original: nus-cs2103-AY2324S2/pe-interim#4215] [original labels: severity.Medium type.DocumentationBug]
Their Response to the 'Original' Bug
[This is the team's response to the above 'original' bug]
Thank you for reporting. However, we have to choose it as NotInScope because this issue doesn't affect the current usage of the product and is not actually a flaw. The provided text explanations are already very clear and concise about how the features are implemented. Diagrams should only be used when there is a need to demonstrate more or if it is better at illustrating an idea. However, in our case, we find that text explanation is already a very effective way of illustrating all the implementation details. Therefore, we suggested that diagrams are not an urgent thing to be added compared to what we have already done.
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)
- [ ] I disagree
Reason for disagreement: [replace this with your explanation]
## :question: Issue response Team chose [`response.NotInScope`] - [ ] I disagree **Reason for disagreement:** [replace this with your explanation]
## :question: Issue severity Team chose [`severity.Low`] Originally [`severity.Medium`] - [x] I disagree **Reason for disagreement:** I understand the concern of the team. However, to put it as severity.Low is too much of a stretch, it is at the very least of severity Medium. This is because it strongly limits the usefulness of the Developer Guide. According to the response: > The provided text explanations are already very clear and concise about how the features are implemented. Diagrams should only be used when there is a need to demonstrate more or if it is better at illustrating an idea. This statement is correct, but slightly irrelevant. While the provided text explanation is definitely clear, it is overly concise. Each subsection only describes three things: model interaction, validation and state saving, and is repeated for all implementation details. The explanation only exposes the Model View Controller pattern of the implementation, but does not suceed in exposing any internal detail for any potential developer to understand. Taking the original AB3 developer guide as a frame of reference, the text explanations given seem rather trivial. Hence, the absence of such diagrams are strongly limit the usability of this section, hence I believe it should be at least Medium. With regards to NotInScope, the work done for the DG seems quite limited (design section largely unchanged, user stories unrefined with duplicates, no instructions for manual testing added), the work done for the product is sufficient, hence it should be okay to classify it as such.
For all implementations in the DG specified, there are no visuals at all. This makes it hard for new users to understand or visualise the structure of the code base, no form of sequence diagrams that can guide the user.
Can continue to use, but it is a strong inconvenience, since the DG is meant to orientate new users.