Week 11 [from Wed Mar 25 noon] - Tutorial

UML diagrams:

• Notation incorrect or not compliant with the notation covered in the module.
• Some other type of diagram used when a UML diagram would have worked just as well.
• The diagram used is not suitable for the purpose it is used.
• The diagram is too complicated.

Use of visuals

• Not enough visuals e.g., screenshots/diagrams
• The visuals are not well integrated to the explanation
• The visuals are unnecessarily repetitive e.g., same visual repeated with minor changes

Use of examples:

• Not enough or too many examples e.g., sample inputs/outputs

Explanations:

• The explanation is too brief or unnecessarily long.
• The information is hard to understand for the target audience. e.g., using terms the reader might not know

Neatness/Correctness:

• looks messy
• not well-formatted
• broken links, other inaccuracies, typos, etc.

• 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 serve as evidence of your ability to 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 v2.1 (hypothetically).
  For an example, see the description of the undo/redo feature implementation in the AddressBook-Level3 (AB3) 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 relevant to that purpose.
  • 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.
• 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.