Week 11 [Mon, Oct 26th] - Project

tP: v2.0

  1. Update UG and DG
  2. Review others' DG during the tutorial
  3. Deliver v2.0 Thu, Oct 29th 23:59
  4. Draft the PPP

tP: v2.0

Intro to tP Week 11

Things to note:

  • Aim to reach the final version in this iteration itself: After this iteration is over, you get a chance to fix your tP bugs (in the project, as well as documentation) without any penalty. What's more, others will help you find those bugs (via tutorial activities).
    To take advantage of the above, try to make your v2.0 (product, DG, and UG) as close to what you intend to submit as your final version (i.e., v2.1).

1 Update UG and DG

This task is time-sensitive. If done later than the iteration deadline given above, it will not be counted as 'done'.

  • Update the User Guide to match the current version of the product.
    • Clearly indicate which features are not implemented yet e.g., tag those features with a Coming soon label.
    • For those features already implemented, ensure their descriptions match the exact behavior of the product e.g., replace mockups with actual screenshots
    • Some things not addressed in the AB3 UG that you might want to consider addressing in your UG (if applicable):
      • Double-clicking the jar might not work on some systems.
      • The app will not work properly if it is placed in a write-protected folder.
      • Mac users using the fullscreen mode for secondary dialogs (e.g., the help dialog) might encounter unexpected behaviors.

  • Similarly, update the Developer Guide (DG).

2 Review others' DG during the tutorial

  • To be done during the tutorial. Please don't do this task before the tutorial as others need time to update their DGs.
  • Read all instructions before you start the activity.
  • Find the team choices you have been allocated to review, as given in the panel below.

Allocation for DG review

  • Decide which of the given team(s) to review:

    • Open the DG link of the team allocated as 'First choice'.
    • Confirm that the DG has significant updates, to the diagrams in particular. If it doesn't, you can try the DG of the 'Second choice' team, and failing that, 'Third choice' team.
    • If none of the three has enough updates, but collectively they have enough updates, you can also review all of them.
    • Failing all above, you can pick any other team(s) to review.
    • Try to give at least 4 comments in total.
    • If the PR already has reviews, you can give your own input of the existing review comments too.

  • Go to the PR of the team(s) you have chosen to review.

  • Review the Design and the Implementation sections w.r.t possible DG bugs (given further down); add your observations as comments.

  • In the PR, add review comments (i.e., in the files changed tab) in the corresponding place of the code.
    • In this case, choose the option rather than option.
  • But if the 'files changed' tab is too laggy, you can add a normal comment instead in the conversation tab.
    • In this case, enter each observation as a separate comment (reason: our bot will count the number of comments you have given to determine if you qualify for participation points)
  • As you know, it is better to 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. An example given below:
  • The understanding you gain from this exercise can indirectly determine how well you do in your own project. Note that your comments will be reviewed by a tutor later.
DG - Possible Bugs

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

Admin tP Grading → DG Bugs → UML Diagrams → Possible Bugs

UML diagrams:

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

Admin tP Grading → General Documentation Bugs

Use of visuals

  • Not enough visuals e.g., screenshots/diagrams
  • The visuals are not well integrated into 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 target user for the product and/or the value proposition is not specified clearly.
  • The explanation is too brief or unnecessarily long.
  • The information is hard for the target audience to understand, e.g., because it uses terms the reader might not know

Neatness/correctness:

  • looks messy
  • not well-formatted
  • broken links, other inaccuracies, typos, etc.
  • hard to read/understand
  • unnecessary repetitions (i.e., hard to see what's similar and what's different)

Also see:

Admin tP: Deliverables → DG → Tips

  • Aim to showcase your documentation skills. The primary objective of the DG is to explain the design/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 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.

FAQ What do we do when the UML notation covered in the course is not enough to model what we want to illustrate?

FAQ Instead of PlantUML, can I use some other tool?

FAQ Can UML diagrams be used in project submissions?

  • 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, method parameters, etc.
        You can use ... (e.g., foo(...)) to indicate parameters have been omitted.
        You can use pseudocode instead of exact method calls e.g., save data in file instead of saveData(content, filename).
        Omit intricate details that complicate the diagram unnecessarily while adding little value to it e.g., exception handling (throw/catch), lambdas, calls to anonymous methods, etc.
        If you feel they are important to the purpose of the diagram (i.e., omitting them can mislead the reader), you can use a UML note to mention that information (as plain text) in the diagram.
    • 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 subcomponents (e.g., a Parser subcomponent inside the Logic component). After that, subcomponents 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 into 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 the 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. You can also use pseudocode instead of actual programming code.
  • Resize diagrams so that the text size in the diagram matches the text size of the main text of the document. See example.

  • After the tutorial, if you are unsure about a concern raised by a reviewer, you can post in the forum to seek the opinion of the teaching team.

3 Deliver v2.0 Thu, Oct 29th 23:59

  • Finish implementing the features you intend to have in the final version.

Ways to level up your tP game:

  • Consider increasing test coverage by adding more tests if it is lower than you would like. Take note of our expectation on test code (given in the panel below).

  • After you have sufficient code coverage, fix remaining code quality problems and bring up the quality to your target level. Note that the quality of the code attributed to you accounts for a significant portion of your final score, graded individually (based on the code attributed to you by the tP code dashboard).

  • Do a . Do the release by the given deadline.
    Do a smoke-test to ensure the jar file works.

    • Include the following files in the release (as separate assets):
      1. JAR file. You may choose any suitable file name, but avoid spaces or special characters in the JAR file name.
      2. UG (in the product website) -- online and updated to match the prouduct.
      3. DG -- similar to the UG
    • It is optional to write detailed release notes for this version.

  • IMPORTANT: ensure your jar file was generated using Java 25 and can work on all major OS'es using JDK 25.

  • As before, wrap up the milestone (i.e., reschedule/close any remaining issues/PRs and close the milestone).

4 Draft the PPP

This task is time-sensitive. If done later than the deadline, it will not be counted as 'done' (i.e., no grace period).

  • Create the first version of your Project Portfolio Page (PPP).Each member needs to create a PPP to describe your contribution to the project.

Admin tP → Deliverables → Project Portfolio Page

Deliverable: Project Portfolio Page (PPP)

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, you should write the remainder 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 the UG: 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/update?
    • 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 teams' products
      • Evidence of technical leadership e.g., sharing useful information in the forum

Keep in mind that evaluators will use the PPP to estimate your project effort. We recommend that you mention things that will earn you a fair score e.g., explain how deep the enhancement is, why it is complete, how hard it was to implement, etc.

  • 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/github_username_in_lower_case.md e.g., docs/team/goodcoder123.md
  • Follow the example in the AddressBook-Level3
  • For the final submission of the PPP (at the end of the tP), you need to save your PPP as a PDF file. Therefore, ensure the PDF version of the PPP looks OK at least a few days before the final submission.

PPP Page Limit

Content Recommended Hard Limit
Overview + Summary of contributions 0.5-1 2
[Optional] Contributions to the User Guide 1
[Optional] Contributions to the Developer Guide 3
  • The page limits given above are after converting to PDF format. The actual amount of content you require is less than what these numbers suggest because the HTML → PDF conversion adds a lot of spacing around content.

Convert the PPP to a PDF to see if the page-count is within expectations (the PDF version can be longer than what you would expect by looking at the HTML version).