Missing table of contents

[xiaohan28]

Missing table of contents on the first page for both UG and DG, perhaps could include to give an overall summary of the contents and also easier for users to click on the specific sections they want to look at.

[soc-se-bot]

[IMPORTANT!: Please do not edit or reply to this comment using the GitHub UI. You can respond to it using CATcher during the next phase of the PE]

Team's Response

Thank you for your feedback.

Issue Explanation:
You correctly observed that the User Guide (UG) and Developer Guide (DG) currently do not include a Table of Contents (ToC) on the first page. Including a ToC would improve readability and allow users to navigate directly to relevant sections, particularly in longer documents.

Expected vs Actual:

• Expected: Presence of a clickable Table of Contents on the first page for easy navigation.
• Actual: Users must scroll or use browser search functions to find relevant sections manually.

Root Cause:
This omission stems from our prioritization of content clarity and functionality coverage. While a Table of Contents is helpful, it was not a core requirement and was deprioritized in favor of ensuring comprehensive and accurate content in each section.

Bug Classification:
We agree that this qualifies as a DocumentationBug, as it relates to how the information is structured and presented, not to any error in functionality or logic.

Severity Reclassification Justification:
We respectfully propose classifying this as VeryLow severity for the following reasons:

1. Functionality is unaffected: All sections of the UG and DG are accessible and clearly labeled. Users can still navigate the documents with standard scrolling or search.
2. Discoverability is preserved: Section headers are visible and follow a logical order. The absence of a ToC does not prevent users from finding the information they need.
3. Alignment with guidelines: As per our module/project guidelines, ToCs are a Quality of Life improvement, not a mandatory requirement. (see photos attached)
4. Minor impact: The benefit of this enhancement is incremental rather than essential to usability or understanding.

Next Steps:
We appreciate your suggestion and will consider including a Table of Contents in future iterations to further improve the user experience. This enhancement will be tracked as a potential polish item in future documentation updates.

Items for the Tester to Verify

❓ Issue response

Team chose [response.NotInScope]

• I disagree

Reason for disagreement: While I understand the team’s intention to prioritize content clarity and functional coverage, this justification does not conflict with including a Table of Contents (ToC). In fact, a ToC complements clarity and usability, especially in long documents like the UG and DG, by enabling readers to quickly locate relevant sections without needing to scroll or search manually.

Additionally, the AB3 Developer Guide includes a table of contents at the beginning of the document. Since our own DG and UG are expected to follow the structure and standards set by AB3, omitting the ToC deviates from these established conventions.

According to the PE guidelines, documentation bugs include formatting issues that slow down and hinder the reader. As seen from the picture below:

A missing ToC fits this description because:

1. It doesn’t prevent access to information but slows the reader down, especially in long documents like UG/DG.
2. It adds effort to navigation, which is avoidable.
3. Unlike a typo, the absence of ToC impacts usability and efficiency, especially for first-time readers.

---