tP: Deliverables

• 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 v1.4 should be good enough to make it usable by at least some of the target users.
• Also note the following constraint:

• Should match v1.4 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.

• Should cover all v1.4 features.
  Ensure those descriptions match the product precisely, as it will be used by peer testers (inaccuracies will be considered bugs).
• Optionally, can also cover future features. Mark those as Coming in v2.0.
• Also note the following constraint:

• Should match the v1.4 implementation.
• Optionally, can include proposed implementations of future features.
• 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 but no need to cover existing AB3 features if you did not touch them.
  • 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.
  • Inaccurate instructions will be considered bugs.
• We highly recommend adding an appendix named Effort that evaluators can use to estimate the total project effort.
  • Keep it brief (~1 page)
  • Explain the difficulty level, challenges faced, effort required, and achievements of the project.
  • Use AB3 as a reference point e.g., you can explain that while AB3 deals with only one entity type, your project was harder because it deals with multiple entity types.

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 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. As a rule of thumb, include at least one structure and one behavior diagram to explain your implementation.
• Keep diagrams simple. The aim is to make diagrams comprehensible, not necessarily comprehensive. However, do not skip necessary details, like visibility, multiplicity etc., that define your implementation. 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.
  • 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, 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.

Website README

• Ensure the Ui.png matches the current product

Some common sense tips for a good product screenshot

Ui.png represents your product in its full glory.

• Before taking the screenshot, populate the product with data that makes the product look good. For example,
• If the product is supposed to show photos, use real photos instead of dummy placeholders.
• If the product doesn't have nice line wrapping for long inputs/outputs, don't use such inputs/outputs for the screenshot.
• It should show a state in which the product is well-populated i.e., don't leave data panels largely blank
• Choose a state that showcase the main features of the product i.e., the login screen is not usually a good choice
• Take a clean screenshot with a decent resolution. Some screenshot tools can capture a specified window only. If your tool cannot do that, make sure you crop away the extraneous parts captured by the screenshot.
• Avoid annotations (arrows, callouts, explanatory text etc.); it should look like the product is in use for real.

 

Reason: Distracting annotations.

 

Reason: Not enough data.

 

Reason: screenshot not cropped cleanly (contains extra background details)

 

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.

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 to evaluate 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 photo.
  • 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 User Guide (Extracts): Reproduce the parts in the User Guide that you wrote. This can include features you implemented as well as features you propose to implement.
  The purpose of allowing you to include proposed features is to provide you more flexibility to show your documentation skills. e.g. you can bring in a proposed feature just to give you an opportunity to use a UML diagram type not used by the actual features.

• [Optional] Contributions to the Developer Guide (Extracts): Reproduce the parts in the Developer Guide that you wrote. Ensure there is enough content to evaluate your technical documentation skills and UML modelling skills. You can include descriptions of your design/implementations, possible alternatives, pros and cons of alternatives, etc.

• [Optional] If you plan to use the PPP in your Resume, you can also include your SE work outside of the module (will not be graded).

PPP Format

• File name: docs/team/githbub_username_in_lower_case.adoc e.g., docs/team/goodcoder123.adoc

• Follow the example in the AddressBook-Level3

• You can use the Asciidoc's include feature to include sections from the developer guide or the user guide in your PPP. Follow the example in the sample.

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.

Owing to the changes in the module deliverables due to COVID-19, you are now required to submit a file containing the UML diagrams.
This is in addition to the documents that you (normally) submit for your project.

UML Objectives

• For you to demonstrate your ability to draw and explain UML diagrams in the context of your product's design.

UML Sections to include

• Each of you should submit one PDF file with the UML diagrams you contributed to the documentation. This can be extracted from your DG.
• Ensure you include a brief description of the UML and how it fits into your product.

UML Page Limit

• Maximum 3 pages.

Demo Duration

• Strictly 18 minutes for a 5-person team, 15 minutes for a 4-person team, 21 minutes for a 6-person team. Exceeding this limit will be penalized.

Demo Target audience

• Assume you are giving a demo to a higher-level manager of your company, to brief him/her on the current capabilities of the product. This is the first time they are seeing the new product you developed but they are familiar with the AddressBook-level3 (AB3) product. The actual audience are the evaluators (the team supervisor and another tutor).

Demo Scope

• Start by giving an overview of the product so that the evaluators get a sense of the full picture early. Include the following:
  • What is it? e.g., FooBar is a product to ensure the user takes frequent standing-breaks while working.
  • Who is it for? e.g., It is for someone who works at a PC, prefers typing, and wants to avoid prolonged periods of sitting.
  • How does it help? Give an overview of how the product's features help to solve the target problem for the target user

Hi, welcome to the demo of our product FooBar. It is a product to ensure the user takes
frequent standing-breaks while working.
It is for someone who works at a PC, prefers typing, and wants to avoid prolonged periods
of sitting.
The user first sets the parameters such as frequency and targets, and then enters a
command to record the start of the sitting time, ... The app shows the length of the
sitting periods, and alerts the user if ...
...

• Each person should do a fair share of the demo. However, it's OK for one member to does all the typing.
• There is no need for each person to demo their own work.
• Present the features in a reasonable order: Organize the demo to present a cohesive picture of the product as a whole, presented in a logical order.
• No need to cover design/implementation details as the manager is not interested in those details.

Demo Structure

• Demo the product using the same executable you submitted.
• Use a sufficient amount of Mr aaa is not a realistic person namerealistic demo data. e.g at least 20 data items. Trying to demo a product using just 1-2 sample data creates a bad impression.

Demo Tips

• Plan the demo to be in sync with the impression you want to create. For example, if you are trying to convince that the product is easy to use, show the easiest way to perform a task before you show the full command with all the bells and whistles.

• Showcase how the feature improves the user’s life rather than simply describe each feature.
• Rehearse the steps well and ensure you can do a smooth demo. Find a golden path and stick to it. Poor quality demos can affect your grade.
• Don’t waste time repeating things the target audience already knows. e.g. no need to say things like "We are students from NUS, SoC".
• No need to introduce next presenter at the end of your part Reason: to save time.

Demo Special circumstances

• If a significant feature was not merged on time: inform the tutor and get permission to show the unmerged feature using your own version of the code. Obviously, unmerged features earn much less marks than a merged equivalent but something is better than nothing.

PE-D Overview

What: The v1.3 is subjected to a round of peer acceptance/system testing, also called the Practical Exam (PE) Dry Run as this round of testing will be similar to the graded Practical Exam that will be done at v1.4.

When, where: uses a 40 minute slot at the start of week 11 lecture

Grading: Taking part in the PE dry run is strongly encouraged as it can affect your grade in the following ways.

• If the product you are allocated to test in the Practical Exam (at v1.4) had a very low bug count, we will consider your performance in PE dry run as well when grading the PE.
• PE dry run will help you practice for the actual PE.
• Taking part in the PE dry run will earn you participation points.
• There is no penalty for bugs reported in your product. Every bug you find is a win-win for you and the team whose product you are testing.

Why:

• To train you to do manual testing, bug reporting, bug assigning of priority ordertriaging, bug fixing, communicating with users/testers/developers, evaluating products etc.
• To help you improve your product before the final submission.

PE-D Preparation

PE-D During the session

PE Overview

PE Preparation

• It's similar to,

PE Phase 1: Bug Reporting

• When, where: Week 13 lecture

PE Phase 1 - Part I Product Testing [60 minutes]

• Test the product and report bugs as described below. You may report both product bugs and documentation bugs during this period.

PE Phase 1 - Part II Evaluating Documents [30 minutes]

• This slot is for reporting documentation bugs only. You may report bugs related to UG and DG.
• For each bug reported, cite evidence and justify. For example, if you think the explanation of a feature is too brief, explain what information is missing and why the omission hinders the reader.

PE Phase 1 - Part III Overall Evaluation [15 minutes]

• To be submitted via TEAMMATES. You are recommended to complete this during the PE session itself, but you have until the end of the day to submit (or revise) your submissions.

PE Phase 2: Developer Response

This phase is for you to respond to the bug reports you received.

Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Monday midnight (within 3 days). However, you are recommended to finish this task ASAP, to minimize cutting into your exam preparation work.

Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.

PE Phase 3: Tester Response

• In this phase you will get to state whether you agree or disagree with the dev response to the bugs you reported. If a bug reported has been subjected to any of the below by the receiving team, you can record your objections and the reason for the objection.
  • not accepted
  • severity downgraded
  • bug type changed
• As before, consider carefully before you object to a team's response. If many of your objections were overruled by the teaching team later, you will lose marks for not being able to evaluate a bug report properly.
• This phase is optional. If you do not respond to a dev response, we'll assume that you agree with it.
• Deadline: Reading week Thursday 2359 (within 2 days)
• Procedure:

PE Phase 4: Tutor Moderation

• In this phase tutors will look through all dev responses you objected to in the previous phase and decide on a final outcome.
• In the unlikely we need your inputs, the tutor will contact you.