This site is from a past semester! The current version will be here when the new semester starts.

tP week 5: Gather requirementstP week 7: Get ready for iterations


tP week 6: Conceptualize the product

  1. Conceptualize v1.2
  2. Draft the UG
  3. Set up the project repo
  4. Get familiar with the code base

tP tasks progress is graded. Completing individual and team tasks are considered for grading the project management component of your project grade.

Most aspects of project progress are tracked using automated scripts. Please follow our instructions closely or else the script will not be able to detect your progress. We prefer not to waste admin resources processing requests for partial credit for work that did not follow the instructions precisely, unless the progress was not detected due to a bug in the script.

Iterative means no need for detailed plans, right?

Continuing from the points raised in the 'Sidebar: Project planning, with a twist' last week ...

Iterative projects typically do not start with a very detailed plan for the final product, because an iterative project accepts that the project requirements can change along the way and hence it is futile to create detailed plans of the final product at the very start.

However, it does not mean we simply keep adding features without any plan and whatever we have at the end is the final product. Instead,

  1. we should have a clear overall direction (e.g., target user, value proposition), and,
  2. we should start each iteration with a clear, detailed, and precise plan of the intended outcome of that iteration.

The plan of the current iteration can change as the iteration progresses (e.g., if we realize we underestimated the effort required for that iteration), but that would be a case of 'changing the current iteration plan', not a case of 'making it up as we go'.

1 Conceptualize v1.2

  • Based on your user stories selected previously, conceptualize the product in terms of how it will look like at v1.2 in the form of a feature list.
    Note down the feature list in your online project notes document.

FAQ: How many features should we put in v1.2?
A: Aim for the smallest set of features the product cannot do without. Even a most basic version of those features is enough. After completing that feature set, you can add more if there is time left.

2 Draft the UG

This task is time-sensitive. If done later than the deadline, it will not be counted as 'done' (i.e., no grace period). Reason: This is 'an early draft'; if done late, it is the 'final version' already.

Deadline: Recommended to finish by the regular weekly project deadline (i.e., before the next Lecture), but give the iP final submission is due this week, you may take until Sunday (Sun, Sep 24th 2359) to submit this.

This deliverable links back to the following point made earlier:

  1. ...
  2. we should start each iteration with a clear, detailed, and precise plan of the intended outcome of that iteration.
  • Collate into a document the complete detailed description of the intended behavior of the product at v1.2.
    • For convenience, let us call it a 'User Guide draft', although it is not meant to resemble the final form of the UG).
    • Use a medium that is convenient for collaboration (e.g., a GoogleDoc).
    • The content need not be polished. Don't waste time in formatting, copy editing etc.
    • You may limit this UG draft to only a description of the features i.e., omit sections such as Quick Start, FAQ, Known Issues, Command summary
  • For each feature, specify the following:
    • What it does
    • The precise command format
    • Example commands (to show how the command is used)
    • Acceptable values for each parameter e.g., if a command takes a person name as a parameter, what inputs are accepted as valid person names?
      • It's not enough to state 'valid name'; you need to specify what rules will be used to determine if the input is a valid name.
      • Yes, making these decisions is not easy -- and that's why we want you to think about them now rather than later. Feel free to discuss in the forum these validation rules.
    • Precise expected outputs when the command succeeds e.g., changes in the GUI, messages shown to the user
    • Precise expected outputs when the command fails e.g., what are the error messages shown when a specific parameter is invalid, missing, specified multiple times, etc.
    • Relevant UI mock-ups (they can be hand-drawn or created using a tool such as PowerPoint, PlantUML, Figma, etc. -- they can be very low-fidelity mock-ups, as they are meant to be temporary)

FAQ: Is it normal to include this level of details in a UG?
Answer: No. Consider this as an 'internal draft' version of the eventual UG. These extra details can be omitted when we transfer this content to the real UG later.

  • You are welcome to (but not required to) follow AB3 when defining the behavior of the new features e.g., use similar command formats, input validation rules, error message formats.
  • Ensure feature-fit: While doing this, ensure the features written by each member fit together to form a cohesive product, and meet other grading criteria of the product design aspect. This might require several rounds of refinement. You are encouraged to pee-review feature details written by other team members and refine the overall product design together.

  • Submission [one person per team]: Save the draft UG as a PDF file, name it {team-id}.pdf e.g., CS2103-T09-2.pdf, and upload to Canvas.
  • Grading criteria: to be considered 'done', the UG draft should meet all the following criteria:
    • Covers all features in the smallest set of features the product cannot do without.
    • Contains all details mentioned above for each of those features
    • Details seem well thought out (i.e., not a half-hearted attempt to satisfy the expected level of details)

Recommended: Divide among team members equally; preferably based on enhancements/features each person would be adding e.g., If you are the person planing to add a feature X, you should be the person to describe the feature X in the User Guide and in the Developer Guide.

Reason: In the final project evaluation your documentation skills will be graded based on sections of the User/Developer Guide you have written.

If you are not sure what we mean by 'enhancements/features each person would be adding' mentioned above, see the panel below for our recommendation on how to divide the tP work:

3 Set up the project repo

  • Set up the team org, the team repo, and individual forks as explained below:

4 Get familiar with the code base

FAQ: Is this a team task or an individual task?
A: It's an individual task (note the icon above), to be done by each member, as we want every member to be familiar with the code base.

  • Ideally, you should do this task in this week (i.e., midnight before the week 6 tutorial), but you may take an extra week (i.e., by the week 7 tutorial) to finish them without penalty.
  • Do the following tutorials to get familiar with the codebase
    • Tutorial 1 - Tracing a Command Execution Path
      • We recommend that you put in a sincere effort into this tutorial because tracing through the code of an unfamiliar code base is an important skill that you will not be able to learn/practice it later in the project as the code will no longer be 'unfamiliar' to you later.
      • Submission [optional]: Post an issue in your team's repo with the title Tutorial: tracing code. In the description, add a 2-3 screenshots you took while at various points of the tutorial. You may close the issue soon after.
    • Tutorial 2 - Adding a new Command
      • If you are an experienced programmer, you can add a different command than the one given in the tutorial.
      • Submission: Do your changes in a branch named tutorial-adding-command, push to your fork, and create a PR from your fork to your team's repo. You may close the PR soon after.
      • FAQ: Do we have to write/update test cases too?
        A: Not a strict requirement, but given the purpose of this tutorial is to learn the code base, it's ideal if you do. It will familiarize you with the existing testing infrastructure. Otherwise you can run into difficulties when you are writing test cases for your own features later.
    • Tutorial 3 - Removing a field from an entity
      • This tutorial is optional to do, but at least give it a quick read.
      • Submission: not required.
  • The PRs created for tutorials need not be merged, unless the changes are actually in line with your project idea.
  • For reference, given below is the workflow you should follow when merging code in your tP:


tP week 5: Gather requirementstP week 7: Get ready for iterations