search

jasmiinee / pe

0 stars 0 forks source link

[DG] Hyperlinks Do Not Lead to the Correct Destinations #2

Open jasmiinee opened 1 week ago

jasmiinee commented 1 week ago

Currently, under the UI component of the DG, the clickable links MainWindow and MainWindow.fxml does not lead me to TrackMate's source code. Instead it brings me to AB3's source code, and thus it does not match the UML diagram for the UI component which is misleading.

image.png

Moreover, the link given for the Storage Component API Storage.java also leads me to AB3 source code instead which does not align with how TrackMate handles their Storage given that the UML diagram has extra components not found within AB3. Thus, this is also misleading.

image.png

nus-pe-script commented 5 days ago

Team's Response

Our team does agree that this is a documentation bug. However, our team does not think that this is a severity medium label, but rather a severity low label. Here's why:

As what being stated in CS2103T website, "Broken/incorrect links: Severity can be Low or Medium depending on how much inconvenience they cause to the reader."

This incorrect links for Storage.java and MainWindows.java do not cause much inconvenience to the users, as the explanation within the developer guide is comprehensive enough for the users to understand. The links rather work as an add-on if the users are keen to find out more. So it might cause slight inconvenience, but definitely not a huge inconvenience.

Items for the Tester to Verify

:question: Issue severity

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

Reason for disagreement: Thank you for your response.

The DG is designed primarily for developers who want to extend or maintain the product. These clickable source code links are more than just supplementary; they are essential for efficient navigation and verification. When these links direct users to AB3’s source code instead of TrackMate’s, they cause confusion and disrupt the development process. This forces developers to spend extra time manually locating the correct files, which is particularly cumbersome given the structural differences between AB3 and TrackMate.

While I would agree with a low severity rating if only a few links were outdated, this issue is more pervasive. Beyond the UI component, links to Main.java, MainApp.java, MainWindow.java, MainWindow.fxml, Model.java, Storage.java and Logic.java are also incorrect. The cumulative impact of multiple broken links significantly hinders the usability of the DG, justifying a medium severity. This aligns with the CS2103T guidelines, as the inconvenience here is not minor but recurring and disruptive.