DG: ref box is not with white background

[m1oojv]

[nus-se-script]

Team's Response

Thank you tester for pointing this out! However, from the textbook, there is no mention of a requirement for a white background. However, I acknowledge that a white background would make it look clearer and neater, hence intend to improve that in the future.

Items for the Tester to Verify

:question: Issue response

Team chose [response.NotInScope]

• [x] I disagree

Reason for disagreement:

It seems that your screenshot has conveniently left out the example shown below that the example given in the course website has a background in the reference frame used (where your DG does not) This is not just a cosmetic preference but serves a functional purpose: to obscure the part of the activation bar that the reference box is referencing.

I must respectfully disagree with the classification of the issue as 'NotInScope'. While it is true that the textbook does not explicitly mandate a white background for the reference box, the standard set by the examples provided in the course materials implicitly suggests a certain level of presentation quality that should be adhered to, like having a background for the reference box and not entirely see through. In the standard examples from the course materials, reference boxes are consistently presented with a background. This design choice is not arbitrary but intentional, serving to distinguish the content within the reference box from the main sequence of events in the diagram. Particularly, it obscures the part of the activation bar that the reference box is referencing, preventing visual confusion.

When an activation bar is visible through a transparent reference box and is not connected to anything or any command in the main diagram, it creates a contradictory visual message. This is especially problematic when compared to the detailed reference diagram, where the activation bar is intricately connected with multiple commands. With 2 contradicting diagrams from the main sequence diagram and the reference diagram, this problem may lead to confusion or misinterpretation. Users may mistakenly find both diagrams contradicting, leading to incorrect assumptions about the system's operation or the sequence of events.

This is not an unreasonable assumption by the user as usually in sequence diagrams, boxes without backgrounds are typically used for loops or conditional statements, where observing the activation bar within the box is critical to understanding the sequence of events. A transparent reference box disrupts this established visual language, misleading users about the significance of the elements within it.

Given these considerations, using a reference box without a background does affect the user’s interpretation of the sequence diagram, and thus, constitutes a bug in our documentation. Users may mistakenly think that the reference box in the main diagram suggests no commands are happening on the activation bar but the reference diagram suggests otherwise and thus confusing and hindering the user, "slow down the reader or require the reader to put more effort than necessary" into understanding your diagram.

Hence, this problem should still be a significant documentation bug.

---