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: Do a practice iteration → v1.1


tP week 6: Conceptualize the product

  1. Conceptualize v1.2
  2. Draft the feature specification
  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. That said, unless a deliverable is marked 'time-sensitive', there is no penalty for missing a deadline provided you catch up with most of them within a few days after the deadline.

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.

Even 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 feature specification

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 can't count as 'early'.

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

  • Objective: 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.

    Furthermore, this deliverable forces you to make some fine-grained product design decisions early, thus giving you a better idea about the complexities that lies ahead, and hence, a better sense of the effort that will be required.

  • Deliverable: Collate into a document the complete detailed description of the intended behavior of the product at v1.2.

    • The intended audience for this document is team members, not end users (i.e., this is not a user guide).
    • 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.

  • For each feature, specify the following:

Purpose: What it does

Command format: The precise command format of the command.
Example commands (to show how the command is used)

For each parameter, specify:

  • Acceptable values e.g., If a command takes a person name as a parameter, what inputs are accepted as valid person names? Some example aspect to consider:
    • Which formats are allowed for dates, times, telephone numbers, etc.?
    • How does extra/leading/trailing spaces affect the value -- for instance is 'John Doe' same as 'John   Doe' (note the multiple spaces in the second name)?
    • How does UPPER/lower case affects values -- is John Doe same as john doe?
    • 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.
  • Error message if the value is not acceptable
  • Rationale for any the validity rule e.g., why only certain characters are allowed for person names?

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 these validation rules in the forum.

Outputs: Precise expected outputs when the command,

  • succeeds e.g., changes in the GUI, messages shown to the user
  • fails e.g., what are the error messages shown when a specific parameter is invalid, missing, specified multiple times, etc.

Duplicate handling: What rules are used to determine if two contacts are duplicates? e.g., is having the same name enough, or all details need to be the same?
How does the application react to such duplicate entries? Reject or accept? Why?

Relevant UI mock-ups, unless the UI will be exatly the same as AB3 (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)

Recommended: Prioritize above finer aspects of features, for example, as must-have (to implement in v1.2) and nice-to-have (i.e., to implement in v1.2 only if there is time)
e.g., you can decide one date format (to accept in user commands) as must-have and two other formats as nice-to-have.

  • It is OK to make compromises when making product decisions as every design option has costs and benefits, and sometimes, costs outweigh the benefits.
    For example, it is fine to restrict the person name to a certain length and a character set even if it is theoretically possible for those restrictions to conflict with some real-world person names. But you need to be aware of such conflicts, justify the restriction (e.g., ease of implementation/display), and know how users can work around such a conflict should they encounter it (e.g., if you app doesn't allow two contacts to have the same name but the user need to store two contacts which are different people with the same name, what should the user do?).

  • 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.
    Should the feature specification include features already in AB3?
    Yes. But you may copy-paste parts of the UG onto your feature spec if that helps.

  • 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 peer-review feature details written by other team members and refine the overall product design together.

  • Submission [one person per team]: Save the file 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 feature spec. 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, but you may take an extra week (i.e., by week 7) to finish.

  • 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: Do a practice iteration → v1.1