Week 10 [Oct 21] - Tutorial

Some background: As you know, our PE includes peer-testing tP products under exam conditions. In the past, we used GitHub as the platform for that -- which was not optimal (e.g., it was hard to ensure the compulsory labels have been applied). As a remedy, some ex-students have been developing an app called CATcher that we would like to use for the PE this semester.

• To be done collectively with sub-team members.
• Add review comments in the corresponding place of the code. But if the diff view is too laggy, you can use a normal comment.
• Choose the Start a review option rather than Add single comment.
• Each person can do their own review, but coordinate with sub-team members to avoid duplicating the same point.
• Phrase your comments as question/doubts (e.g., Is this format correct? Should it be ... instead?) rather than directives (e.g., Change this to ...).
• Where possible, use screenshots from their DG in your comments, preferably with annotations. This is particularly useful when commenting on diagrams.
• Do not finalize the review at this stage. Just keep adding comments.
• The understanding you gain from this exercise can indirectly determine how well you do in your own project. If you have even the slightest doubt about your observations in this exercise, please discuss it with the tutor to ensure you have the right understanding of the criteria used.

DG Expectations

Pay attention to these as they are same as the final evaluation criteria of the DG.

Also see:

• Aim to showcase your documentation skills. The stated objective of the DG is to explain the implementation to a future developer, but a secondary objective is to show evidence that you can document deeply-technical content using prose, examples, diagrams, code snippets, etc. appropriately. To that end, you may also describe features that you plan to implement in the future, even beyond v1.4 (hypothetically).
  For an example, see the description of the undo/redo feature implementation in the AddressBook-Level3 developer guide.
• Use multiple UML diagram types. Following from the point above, try to include UML diagrams of multiple types to showcase your ability to use different UML diagrams.
• Keep diagrams simple. The aim is to make diagrams comprehensible, not necessarily comprehensive. Ways to simplify diagrams:
  • Omit less important details. Examples:
    • a class diagram can omit minor utility classes, private/unimportant members; some less-important associations can be shown as attributes instead.
    • a sequence diagram can omit less important interactions, self-calls.
  • Omit repetitive details e.g., a class diagram can show only a few representative ones in place of many similar classes (note how the AB3 Logic class diagram shows concrete *Command classes).
  • Limit the scope of a diagram. Decide the purpose of the diagram (i.e., what does it help to explain?) and omit details not related to it. In particular, avoid showing lower-level details of multiple components in the same diagram unless strictly necessary e.g., note how the this sequence diagram shows only the detailed interactions within the Logic component i.e., does not show detailed interactions within the model component.
  • Break diagrams into smaller fragments when possible.
    • If a component has a lot of classes, consider further dividing into sub-components (e.g., a Parser sub-component inside the Logic component). After that, sub-components can be shown as black-boxes in the main diagram and their details can be shown as separate diagrams.
    • You can use ref frames to break sequence diagrams to multiple diagrams. Similarly, rakes can be used to divide activity diagrams.
  • Stay at the highest level of abstraction possible e.g., note how this sequence diagram shows only the interactions between architectural components, abstracting away the interactions that happen inside each component.
  • For some more examples, see here.
• Integrate diagrams into the description. Place the diagram close to where it is being described.
• Use code snippets sparingly. The more you use code snippets in the DG, and longer the code snippet, the higher the risk of it getting outdated quickly. Instead, use code snippets only when necessary and cite only the strictly relevant parts only.
• Resize diagrams so that the text size in the diagram matches the the text size of the main text of the diagram. See example.

These class diagrams seem to have lot of member details, which can get outdated pretty quickly:

---

This class diagram seems to have too many classes:

---

These sequence diagrams are bordering on 'too complicated':

In this negative example, the text size in the diagram is much bigger than the text size used by the document:

It will look more 'polished' if the two text sizes match.

Architecture

• The Architecture diagram uses intuitive symbols.
• No indiscriminate use of double-headed arrows.
• Any architecture-level diagrams do not contain lower-level details.
• The description given is understandable and sufficiently high-level.

Diagrams

• Uses the correct UML notation.
  If you notice UML notation errors, please point them out.
• Not cluttered with too much unnecessary details.
• Each diagrams is relatively simple and easy to understand.
• Uses multiple types of diagrams (ideal: uses Class Diagrams, Object Diagrams, Sequence Diagrams, Activity Diagrams)
• Diagrams are well-integrated into the description.
• Not repetitive (opposite: many similar diagrams with minor differences).

Descriptions

• Easy to understand/follow (were you able to understand their design?)
• Just enough information: Not too much information. All important information is given.

Overall

• Polished: The document looks neat, well-formatted, and professional.
  e.g., Are the diagrams resized to match the text size of the main document?