search

Nanxi-Huang / pe

0 stars 0 forks source link

Diagrams Do Not Match Product #8

Open Nanxi-Huang opened 3 years ago

Nanxi-Huang commented 3 years ago

The diagrams for architecture components and some individual components still shows traces of AddressBook, and not the product A-Bash Book. The developers for this product might have forgotten to change the diagrams to accommodate their own products.

Screenshot 2021-04-16 at 3.29.38 PM.png

Screenshot 2021-04-16 at 3.30.25 PM.png

nus-pe-bot commented 3 years ago

Team's Response

Severity downgraded from high to medium because this issue will only cause occasional inconvenience to readers but they can continue to use the developer guide.

However, we are rejecting this issue. A-Bash Book (ABB) is a brownfield project built on top of the existing code base of AB3.

Therefore, some of our classes and methods that we use are the existing ones from AB3 and we have not changed their names.

Our code still uses AB3's AddressBookParser and we have not changed the class name. Therefore, the diagram is still accurate and is representative of our implementation.

The 'Original' Bug

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

DG has obvious traces of the original AddressBook 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.

Similarly, lots of diagrams are unchanged from AddressBook DG, including the name of the methods described in the Implementation section.

Screenshot 2021-04-16 at 3.30.03 PM.png Screenshot 2021-04-16 at 3.40.11 PM.png

[original: nus-cs2103-AY2021S2/pe-interim#2817] [original labels: severity.High type.DocumentationBug]

Their Response to the 'Original' Bug

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

Severity downgraded from high to medium because this issue will only cause occasional inconvenience to readers but they can continue to use the developer guide.

However, we are rejecting this issue. A-Bash Book (ABB) is a brownfield project built on top of the existing code base of AB3.

Therefore, some of our classes and methods that we use are the existing ones from AB3 and we have not changed their names. The reason we did not change the AddressBook terms in our code base was that ABB is fundamentally still an address book used for storing company contacts thus we felt that using the AddressBook terms was fitting and changing it to ABashBook was not necessary.

The method you highlighted in your screenshot saveAddressBook(addressBook) is representative of our code base as we are still using the same method from AB3, therefore we have rejected this issue.

Another example where we used AddressBook would be the AddressBookParser in our Logic component diagram. Our code still uses AB3's AddressBookParser and we have not changed the class name, therefore, the Logic diagram is still accurate and is representative of our implementation.

For your second screenshot, do note that the term address book used here is an English term and not referring to AB3.

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)

Reason for disagreement: [replace this with your explanation]

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: It is quite clear that the team copy most of the original AddressBook Developer Guide. Even if this application is a brownfield project built on top of the existing code base of AB3, the team should still have their own developer guide that is about their own product.

If this argument is accepted, then every team from this course should just reuse most of the diagrams from AddressBook DG and not spend effort in making diagrams that describe their own products.

In addition, the team mentioned that they did not even change most of the class and method names in the actual code of their product, this also reflects a lot about the quality of this project.

:question: Issue severity

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

Reason for disagreement: This bug should be of severity.High because there is no escape that the target readers will find out that most part of this Developer Guide is describing another application instead of A-Bash Book. The similarity in names does not make it acceptable.

As such, this developer guide is considered to be less useful to the target user and might even cause major confusions, because most of the contents do not match the actual product (imagine a target reader who does not know about AddressBook reading this).