Glossary table broke off into next page

[m1oojv]

Glossary table broke off into next page - may affect users when reading documentation

did not efficiently use page break to solve this issue

[nus-se-bot]

Team's Response

No details provided by team.

The 'Original' Bug

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

Logic component diagrams are in a different page than expected.

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 sentences introducing the diagrams are in a different page than the diagram itself. This could hinder/confuse readers which do not have pages scrolling vertically but have it set up horizontally instead.

In the screenshots below, the black bars represent a separate page.

Diagram 1:

Diagram 2:

---

_{[original: nus-cs2103-AY2324S1/pe-interim#242] [original labels: severity.Low type.DocumentationBug]}

Their Response to the 'Original' Bug

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

Hi tester. Based on the website, we are not required to optimise page breaks unless it hinders the reader. The diagrams are not split into two pages, and also the page breaks are not of a large margin. As such we do believe that this does not hinder the readers.

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)

• [x] I disagree

Reason for disagreement: The original bug deals with the issue of formatting in the Developer Guide.

This issue deals with formatting in the User Guide.

Since one can be fixed independently of the other (since you're editting 2 separate files and downloading 2 separate pdfs from chrome), they are not duplicates (as per the module website).

Prof has also justified this in the forum that this should not be duplicates as fixing one does not automatically fix the other.

Moreover, your team decided to mark this as a duplicate without any justification.

---

## :question: Issue response Team chose [`response.Rejected`] - [x] I disagree **Reason for disagreement:** I appreciate your perspective on the page break issue. However, I must respectfully disagree with your assessment as it does significantly hinder the reader. The glossary table breaking off into the next page, as evidenced in the screenshot, does impact the readability and user experience of the documentation. Proper formatting, including efficient use of page breaks, is crucial in technical documentation to ensure that information is easily accessible and comprehensible. When a table spills over to another page without clear demarcation or warning, it can disrupt the flow of reading and potentially lead to confusion or misinterpretation of information. This is particularly important for users who might not have vertically scrolling pages and rely on the layout presented. Tables and diagrams should be properly formatted and contained within single pages where possible (and it's not that difficult as well, with a simple before the table. This small change could greatly improve the user experience and clarity of the documentation. The assumption of " the page breaks are not of a large margin and will not affect the user" is not applicable to every user. Users with disabilities or those using screen readers might find it challenging to navigate documents where tables break across pages. Screen readers may not effectively convey the continuity of the table, leading to confusion. Some users may even decide to print out your User Guide and thus having your table spill over to the other page is a significant problem and hinder the user in refering to the table, especially for such an important table (Glossary Table) that the user will be refering to multiple times due to the technical terms used in the guide. This perspective overlooks a key aspect of user experience in document design. Even small formatting inconsistencies, such as a glossary table breaking off into the next page or sentences introducing diagrams being on different pages, can disrupt the flow of information. For readers, especially those who may be referencing the document in formats that don't support continuous vertical scrolling, such breaks can be confusing and require additional effort to navigate. In a technical document, users often need to refer back to specific sections like glossaries for definitions. If a table breaks across two pages, finding the right information quickly becomes more difficult, disrupting the workflow. When information is split awkwardly across pages, it increases the cognitive load on the reader. They have to mentally piece together information that should be cohesive, which can be especially taxing if the document is technical in nature, like your User Guide. . Above shows a specific guideline from the teaching team, which clearly states: "Cases such as a diagram being split between pages are considered bugs, because they hinder the reader." Just as a diagram split between pages is acknowledged as a bug due to its negative impact on readability, the same principle should apply to our situation with the glossary table breaking off into the next page. This is not merely a minor formatting issue; it's a substantial impediment to the user's ability to effectively consume and understand the information presented (as phrased from the teaching team "require the reader to put more effort than necessary") . The teaching team's statement underscores the importance of seamless information presentation in technical documentation. When a reader encounters a table or a diagram split across pages, it disrupts their cognitive flow, requiring additional effort to piece together disjointed information. Furthermore, In your response, is attached a screenshot from the teaching team that states: "Any problems with the PDF files - messed up formatting can be reported as bugs". Therefore, this bug of messed up formatting of your glossary table is a bug and is of severity. Low as it does hinder the user in using your pdf version of your User Guide (especially those that prints out documents and do not use continuous scrolling pdf readers) and this glossary table is such a vital part of your user guide, thus not purely cosmetic.

---