Week 13 [Fri, Nov 6th] - Project

• Should be an executable jar file.
• Should be i.e., it can be used by end-usersreleasable. While some features may be scheduled for later versions, the features in v3.0 should be good enough to make it usable by at least some of the target users.

• Should match v3.0 deliverables i.e., executable, docs, website, etc.
• To be delivered as a Git repo. Ensure your GitHub team repo is updated to match the executable.

• The main content you add should be in the docs/UserGuide.md file (for ease of tracking by grading scripts).
• Should cover all v3.0 features.
  Ensure those descriptions match the product precisely, as it will be used by testers (inaccuracies will be considered bugs).
• Optionally, can also cover future features. Mark those as Coming soon.

• The main content you add should be in the docs/DeveloperGuide.md file (for ease of tracking by grading scripts).
  If you use PlantUML diagrams, commit the diagrams as .puml files in the docs/diagrams folder.
• Should match the v3.0 implementation.

• OPTIONAL You can include proposed implementations of future features.
• OPTIONAL Include an appendix named Instructions for Manual Testing, to give some guidance to the tester to chart a path through the features, and provide some important test inputs the tester can copy-paste into the app.
  • Cover all user-testable features.
  • No need to give a long list of test cases including all possible variations. It is upto the tester to come up with those variations.
  • Information in this appendix should complement the UG. Minimize repeating information that are already mentioned in the UG.
  • Inaccurate instructions will be considered bugs.

DG Tips

• 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 v3.0 (hypothetically).
  For an example, see the description of the undo/redo feature implementation in the AddressBook-Level3 developer guide.
• Diagramming tools:

  • AB3 uses PlantUML (see the guide Using PlantUML @SE-EDU/guides for more info).
    

  • You may use any other tool too (e.g., PowerPoint). But if you do, note the following:
    Choose a diagramming tool that has some 'source' format that can be version-controlled using git and updated incrementally (reason: because diagrams need to evolve with the code that is already being version controlled using git). For example, if you use PowerPoint to draw diagrams, also commit the source PowerPoint files so that they can be reused when updating diagrams later.

  • Can i.e., automatically reverse engineered from the Java codeIDE-generated UML diagrams be used in project submissions? Not a good idea. Given are three reasons each of which can be reported by evaluators as 'bugs' in your diagrams, costing you marks:

    • They often don't follow the standard UML notation (e.g., they add extra icons).
    • They tend to include every little detail whereas we want to limit UML diagrams to important details only, to improve readability.
    • Diagrams reverse-engineered by an IDE might not represent the actual design as some design concepts cannot be deterministically identified from the code. e.g., differentiating between multiplicities 0..1 vs 1, composition vs aggregation
• 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 using a placeholder XYZCommand).
  • 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.
  • 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.
  • Use visual representations as much as possible. E.g., show associations and navigabilities using lines and arrows connecting classes, rather than adding a variable in one of the classes.
  • For some more examples of what NOT to do, 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. You can also use pseudo code instead of actual programming code.
• 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.

At the end of the project each student is required to submit a Project Portfolio Page.

PPP Objectives

• For you to use (e.g. in your resume) as a well-documented data point of your SE experience
• For evaluators to use as a data point for evaluating your project contributions

PPP Sections to include

• Overview: A short overview of your product to provide some context to the reader. The opening 1-2 sentences may be reused by all team members. If your product overview extends beyond 1-2 sentences, the remainder should be written by yourself.
• Summary of Contributions --Suggested items to include:
  • Code contributed: Give a link to your code on tP Code Dashboard. The link is available in the Project List Page -- linked to the icon under your profile picture.
  • Enhancements implemented: A summary of the enhancements you implemented.
  • Contributions to documentation: Which sections did you contribute to the UG?
  • Contributions to the DG: Which sections did you contribute to the DG? Which UML diagrams did you add/updated?
  • Contributions to team-based tasks :
  • Review/mentoring contributions: Links to PRs reviewed, instances of helping team members in other ways
  • Contributions beyond the project team:
    • Evidence of helping others e.g. responses you posted in our forum, bugs you reported in other team's products,
    • Evidence of technical leadership e.g. sharing useful information in the forum

• [Optional] Contributions to the Developer Guide (Extracts): Reproduce the parts in the Developer Guide that you wrote. Alternatively, you can show the various diagrams you contributed.
• [Optional] Contributions to the User Guide (Extracts): Reproduce the parts in the User Guide that you wrote.

PPP Format

• File name (i.e., in the repo): docs/team/githbub_username_in_lower_case.md e.g., docs/team/goodcoder123.md
• Follow the example in the AddressBook-Level3

PPP Page Limit

• The page limits given above are after converting to PDF format. The actual amount of content you require is actually less than what these numbers suggest because the HTML → PDF conversion adds a lot of spacing around content.

When setting up your team repo, you would be configuring the GitHub Pages feature to publish your documentation as a website.

Website Home page

• Update to match your product.

Website AboutUs Page

• Use a suitable profile photo.

• Include a link to each person's PPP page.
• Team member names match full names used by LumiNUS.

Website UG (Web Page)

• Should match the submitted PDF file.

Website DG (Web Page)

• Should match the submitted PDF file.