- Conceptualize v1.0
- Draft the UG midnight before the tutorial
- Refine the product design
1 Conceptualize v1.0
- Based on your user stories selected previously, conceptualize the product in terms of how it will look like at v1.0 in the form of a
feature list .
Note down the feature list in your online project notes document.
Requirements → Specifying Requirements → Feature Lists →
Feature list: A list of features of a product grouped according to some criteria such as aspect, priority, order of delivery, etc.
A sample feature list from a simple Minesweeper game (only a brief description has been provided to save space):
- Basic play – Single player play.
- Difficulty levels
- Medium levels
- Advanced levels
- Versus play – Two players can play against each other.
- Timer – Additional fixed time restriction on the player.
- ...
2 Draft the UG midnight before the tutorial
- Draft a user guide in a convenient medium (e.g., a GoogleDoc) to describe what the product would be like when it is at v1.0.
- We recommend that you follow the AB3 User Guide in terms of structure and format.
- As this is a very rough draft and the final version will be in a different format altogether (i.e., in Markdown format), don't waste time in formatting, copy editing etc. It is fine as long as the tutor can get a rough idea of the features from this draft. You can also do just the 'Features' section and omit the other parts.
- Do try to come up with concrete command syntax for the CLI commands that you will deliver at v1.0.
- Include only features that will be delivered in v1.0.
- Consider including examples of expected outputs too.
- Submission [one person per team]: Save the draft UG as a PDF file, name it
{team-id}.pdfe.g.,CS2113-T09-2.pdf, and upload to LumiNUS.
Recommended: Divide i.e., work related to the User Guide and the Developer Guidedocumentation work 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.
Admin tP: Grading → Documentation
4. Project Grading: Documentation [ 10 marks]
Evaluates: your contribution to project documents
Method: Evaluated in two steps.
- Step 1: Evaluate the whole UG and DG. This is evaluated by peers who tested your product, and tutors.
Admin tP → PE → Grading Instructions for User Guide
Evaluate based on fit-for-purpose, from the perspective of a target user.
For reference, the AB3 UG is here.
Admin tP → PE → Grading Instructions for Developer Guide
Evaluate based on fit-for-purpose from the perspective of a new team member trying to understand the product's internal design by reading the DG.
For reference, the AB3 DG is here.
- Step 2: Evaluate how much of that effort can be attributed to you. This is evaluated by team members, and tutors.
Admin Peer Evaluations → Questions used for Evaluating the Contribution to the UG
Admin Peer Evaluations → Questions used for Evaluating the Contribution to the DG
Uses the Equal Share +/- N% scale for the answer
- In addition, UG and DG bugs you received in the PE will be considered for grading this component.
These are considered UG bugs (if they hinder the reader):
Use of visuals
- Not enough visuals e.g., screenshots/diagrams
- The visuals are not well integrated to 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 explanation is too brief or unnecessarily long.
- The information is hard to understand for the target audience. e.g., using 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)
These are considered DG bugs (if they hinder the reader):
Those given as possible UG bugs ...
These are considered UG bugs (if they hinder the reader):
Use of visuals
- Not enough visuals e.g., screenshots/diagrams
- The visuals are not well integrated to 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 explanation is too brief or unnecessarily long.
- The information is hard to understand for the target audience. e.g., using 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)
UML diagrams:
- Notation incorrect or not compliant with the notation covered in the module.
- Some other type of diagram used when a UML diagram would have worked just as well.
- The diagram used is not suitable for the purpose it is used.
- The diagram is too complicated.
Code snippets:
- Excessive use of code e.g., a large chunk of code is cited when a smaller extract would have sufficed.
Problems in User Stories. Examples:
- Incorrect format
- All three parts are not present
- The three parts do not match with each other
- Important user stories missing
Problems in NFRs. Examples:
- Not really a Non-Functional Requirement
- Not scoped clearly (i.e., hard to decide when it has been met)
- Not reasonably achievable
- Highly relevant NFRs missing
Problems in Glossary. Examples:
- Unnecessary terms included
- Important terms missing
3 Refine the product design
- Review the UG to ensure the features written by each member fit together to form a cohesive product. Note that cohesiveness of the product can affect the grading of the product design aspect.
Admin tP: Grading → Product Design
1. Project Grading: Product Design [ 5 marks]
Evaluates:
- how well your features fit together to form a cohesive product
(not how many features or how big/novel/interesting/difficult the features are) - how well it matches the target user
Evaluated by:
- the teaching team (based on product demo and user guide)
- peers from other teams (based on peer testing and user guide)
Admin tP → PE → Grading Instructions for Product Design
Evaluate based on the User Guide and the actual product behavior.
| Criterion | Unable to judge | Low | Medium | High |
|---|---|---|---|---|
target user |
Not specified | Clearly specified and narrowed down appropriately | ||
value proposition |
Not specified | The value to target user is low. App is not worth using | Some small group of target users might find the app worth using | Most of the target users are likely to find the app worth using |
optimized for target user |
Not enough focus for CLI users | Mostly CLI-based, but cumbersome to use most of the time | Feels like a fast typist can be more productive with the app, compared to an equivalent GUI app without a CLI | |
feature-fit |
Many of the features don't fit with others | Most features fit together but a few may be possible misfits | All features fit together to for a cohesive whole |
In addition, feature flaws reported in the PE will be considered when grading this aspect.
Note that 'product design' or 'functionality' are not critical learning outcomes of the tP. Therefore, the bar you need to reach to get full marks will be quite low. For example, the Medium level in the rubric given in the panel above should be enough to achieve full marks. Similarly, only cases of excessive 'feature flaw' bugs will affect the score.
These are considered feature flaws:
The feature does not solve the stated problem of the intended user i.e., the feature is 'incomplete'
Hard-to-test features
Features that don't fit well with the product
Features that are not optimized enough for fast-typists or target users