search

AudreyFelicio / pe

0 stars 0 forks source link

Missing Sequence Diagrams and Example Usage Scenarios #10

Open AudreyFelicio opened 3 years ago

AudreyFelicio commented 3 years ago

In the implementation section in the DG, the Recommend S/Uand Show progress towards target CAP is missing example usage scenario and sequence diagrams. Other sections in implementation have sequence diagrams. This makes the developer guide incomplete and inconsistent.

nus-se-bot commented 3 years ago

Team's Response

As per the CS2103T website, it is not a requirement to have the same type of UML diagram for all the features in the DG. For reference, please refer to https://nus-cs2103-ay2021s1.github.io/website/admin/tp-deliverables.html under Developer Guide which does not state that it is necessary to have the same type of UML diagram. The type and number of UML diagrams included for each feature is up to the individual team member who wrote that specific feature. Hence this cannot be considered a bug.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: Firstly, thank you for the response.

Although it is never stated to have the same type of UML diagram for all features in the DG, my point that the Developer Guide is incomplete still holds.

From the viewpoint of the developer, having example usage scenarios and sequence diagrams is very helpful to gain a high-level overview of what the implementation does. Without having a good understanding of what the implementation does, it will be hard for a developer to do his/her job maintaining or extending features of MyMods.

Therefore, not including example usage scenarios and sequence diagrams make the features Recommend S/U and Show progress towards target CAP hard to understand for the developers reading them. This defeats the purpose of Developer Guide in the first place, because it does not provide the necessary help and guidance needed for future developers for these two features.

Now, my second point that the Developer Guide is inconsistent also still holds.

I agree that the type and number of UML diagrams included is up to the writer, but the writer must include at least one diagram so that the format will be consistent throughout the implementation part. Although this is a minor thing, I would say that the Developer Guide is not well formatted due to inconsistencies in whether to include UML diagrams or example usage scenarios.

To conclude, I feel that the developers are missing the bigger picture. UML diagrams are not a requirement does not mean that the writers of the Developer Guide can just anyhow omit. This is a valid bug because the lack of diagrams and usage scenarios make the Developer Guide hard to understand and format not consistent and therefore incomplete and inconsistent.

:question: Issue severity

Team chose [severity.VeryLow] Originally [severity.Medium]

Reason for disagreement: As stated in my disagreement reasoning for rejection, the missing diagrams make the Developer Guide for the two features mentioned hard to understand. Note also that the two features mentioned are some of the key features of MyMods. Therefore, it will cause occasional inconvenience to developers tasked with extending or maintaining those two features. This should be at least severity.Medium.