search

zsoh97 / pe

0 stars 0 forks source link

no table title for command summary #11

Open zsoh97 opened 4 years ago

zsoh97 commented 4 years ago

image.png

nus-pe-bot commented 4 years ago

Team's Response

Thank you for your report.

If we are understanding this correctly, the issue here is that there is no caption attached to the bottom of this command summary table. However, we believe it is not a requirement in this instance as:

  1. This table is found under the section heading of 6. Command Summary.
  2. This is a reference table and not a diagram/figure.
  3. The table used in AB3's DG also does not include a caption.

Thus, we believe a caption would not be helpful and would be redundant.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: AB3 should not be used as a guideline for proper formatting of documentation as the AB3 documentations (UG and DG) are incomplete and not of optimal quality as well. Instead, the developers should follow the guidelines taught under the CS2101 module.

From 10.2 UG and DG Peer review exercise:

image.png

"Are formal graphics labelled appropriately? is the format standardized?"

This should suggest that all formal diagrams should be labelled according to the same format.

Labelling of the table can be useful for referencing the tables used in a DG.

:question: Issue severity

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

Reason for disagreement: Given the importance of tables to better present the information of the project so that readers can better understand the diagram, for future documentations of this project, more tables would be added, not labelling the tables could affect the overall experience of developers trying to navigate the DG and reduce the effectiveness of the DG. This absence of labelling of tables can be observed in sections 4, 4.2, 4.3 and in the example given. Given the repeated occurences and from the developers' reply, this was a purposed implementation by the team and not some type/format error from converting adoc to pdf. This affects the readability of the documentation as a whole and provides incovenience to readers as the tables cannot be referenced. Thus, the severity should be considered Medium.

The severity level should definitely not be very low(purely cosmetic).