CS2103/T Website - Admin: tP: v1.1 [week 7]

Update project website: AboutUs, ContactUs, README
Update the UG
Update the DG: user stories, glossary, NFRs, use cases
Wrap up v1.1
Draft a rough project plan
start implementing a minimal version of your enhancement

1 Update project website: `AboutUs`, `ContactUs`, `README`

Recommended procedure for updating docs:

Divide among yourselves who will update which parts of the document(s).
Update the team repo by following the recommended workflow.

Update the following pages in your project repo:

About Us page: This page is used for module admin purposes. Please follow the format closely or else our scripts will not be able to give credit for your work.
- Replace info of SE-EDU developers with info of your team. Include a suitable photo as described here.
- Including the name/photo of the supervisor/lecturer is optional.
- The filename of the profile photo (even a placeholder image) should be doc/images/githbub_username_in_lower_case.png e.g. docs/images/damithc.png. If your photo is in jpg format, name the file as .png anyway.
- Indicate the different roles played and responsibilities held by each team member. You can reassign these roles and responsibilities (as explained in Admin Project Scope) later in the project, if necessary.

Contact Us Page: Update to match your product.
README.adoc page: Update it to match your project.
- Add a UI mockup of your intended final product. Note that the image of the UI should be docs/images/Ui.png so that it can be downloaded by our scripts. Limit the file to contain one screenshot/mockup only and ensure the new image is roughly the same height x width proportions as the original one. Reason: when we compile these images from all teams into one page (example), yours should not look out of place.
- The original README.adoc file (which doubles as the landing page of your project website) is written to read like the introduction to an SE learning/teaching resource. You should restructure this page to look like the home page of a real product (not a school project) targeting real users. For instance,
  - remove references to addressbook-level2
  - remove Learning Outcomes
  - mention your target users
  - add a marketing blurb
- Update the link of the Travis build status badge () so that it reflects the build status of your team repo. For the other badges,
  - either set up the respective tool for your project (AB3 Developer Guide has instructions on how to set up AppVeyor and Coveralls) and update the badges accordingly,
  - or remove the badge.
- Acknowledge the original source of the code i.e. AddressBook-Level3 project created by SE-EDU initiative at https://se-education.org
Website heading: Update the website heading to match your product. Currently it is set to AddressBook Level 3 - ....

If you updated the above pages correctly, details of your project in the Project List Page should look neat and complete i.e., no broken links.

2 Update the UG

Move the draft UG into the User Guide page in your repository. If a feature is not implemented, mark it as 'Coming in v2.0' (example).
As mentioned in week 6, we recommend that each person updates their own part of the docs so that we can easily track the contribution of each member using RepoSense.
While it is more convenient for one person to update the entire UG, splitting the work will give you a good opportunity to learn to deal with merge conflicts.

3 Update the DG: user stories, glossary, NFRs, use cases

Update the following in the DG, based on your project notes from the previous weeks.
Some examples of these can be found in the AB3 Developer Guide.
- Target user profile, value proposition, and user stories: Update the target user profile and value proposition to match the project direction you have selected. Give a list of the user stories (and update/delete existing ones, if applicable), including priorities. This can include user stories considered but will not be included in the final product.
- Use cases: Give use cases (textual form) for a few representative user stories that need multiple steps to complete. e.g. Adding a tag to a person (assume the user needs to find the person first)
- Non-functional requirements: Note: Many of the given project constraints can be considered NFRs. You can add more. e.g. performance requirements, usability requirements, scalability requirements, etc.
- Glossary: Define terms that are worth recording.
- [Optional] Product survey: Explore a few similar/related products and describe your findings i.e. Pros, cons, (from the target user's point of view).

Requirements → Specifying Requirements → Use Cases →

Introduction

Use Case: A description of a set of sequences of actions, including variants, that a system performs to yield an observable result of value to an actor.[ 📖 : uml-user-guideThe Unified Modeling Language User Guide, 2e, G Booch, J Rumbaugh, and I Jacobson ]

Actor: An actor (in a use case) is a role played by a user. An actor can be a human or another system. Actors are not part of the system; they reside outside the system.

A use case describes an interaction between the user and the system for a specific functionality of the system.

System: Online Banking System (OBS)
Use case: UC23 - Transfer Money
Actor: User
MSS:
  1. User chooses to transfer money.
  2. OBS requests for details of the transfer.
  3. User enters the requested details.
  4. OBS requests for confirmation.
  5. User confirms.
  6. OBS transfers the money and displays the new account balance.
  Use case ends.

Extensions:
  3a. OBS detects an error in the entered data.
    3a1. OBS requests for the correct data.
    3a2. User enters new data
    Steps 3a1-3a2 are repeated until the data entered are correct.
    Use case resumes from step 4.
  
  3b. User requests to effect the transfer in a future date.
      3b1. OBS requests for confirmation.
      3b2. User confirms future transfer.
      Use case ends.
  
  *a. At any time, User chooses to cancel the transfer.
      *a1. OBS requests to confirm the cancellation.
      *a2. User confirms the cancellation.
      Use case ends.

System: A Learning Management System (LMS)
Actor: Student
Use Case: Upload file
1. Student requests to upload file
2. LMS requests for the file location
3. Student specifies the file location
4. LMS uploads the file

UML includes a diagram type called use case diagrams that can illustrate use cases of a system visually, providing a visual ‘table of contents’ of the use cases of a system.

In the example on the right, note how use cases are shown as ovals and user roles relevant to each use case are shown as stick figures connected to the corresponding ovals.

Use cases capture the functional requirements of a system.

Requirements → Requirements →

Non-Functional Requirements

Requirements can be divided into two in the following way:

Functional requirements specify what the system should do.
Non-functional requirements specify the constraints under which system is developed and operated.

Some examples of non-functional requirement categories:

Data requirements e.g. size, how often do data changevolatility, saving data permanenetlypersistency etc.,
Environment requirements e.g. technical environment in which system would operate or need to be compatible with.
Accessibility, Capacity, Compliance with regulations, Documentation, Disaster recovery, Efficiency, Extensibility, Fault tolerance, Interoperability, Maintainability, Privacy, Portability, Quality, Reliability, Response time, Robustness, Scalability, Security, Stability, Testability, and more ...

Business/domain rules: e.g. the size of the minefield cannot be smaller than five.
Constraints: e.g. the system should be backward compatible with data produced by earlier versions of the system; system testers are available only during the last month of the project; the total project cost should not exceed $1.5 million.
Technical requirements: e.g. the system should work on both 32-bit and 64-bit environments.
Performance requirements: e.g. the system should respond within two seconds.
Quality requirements: e.g. the system should be usable by a novice who has never carried out an online purchase.
Process requirements: e.g. the project is expected to adhere to a schedule that delivers a feature set every one month.
Notes about project scope: e.g. the product is not required to handle the printing of reports.
Any other noteworthy points: e.g. the game should not use images deemed offensive to those injured in real mine clearing activities.

We may have to spend an extra effort in digging NFRs out as early as possible because,

NFRs are easier to miss e.g., stakeholders tend to think of functional requirements first
sometimes NFRs are critical to the success of the software. E.g. A web application that is too slow or that has low security is unlikely to succeed even if it has all the right functionality.

Given below are some requirements of TEAMMATES (an online peer evaluation system for education). Which one of these are non-functional requirements?

a. The response to any use action should become visible within 5 seconds.
b. The application admin should be able to view a log of user activities.
c. The source code should be open source.
d. A course should be able to have up to 2000 students.
e. As a student user, I can view details of my team members so that I can know who they are.
f. The user interface should be intuitive enough for users who are not IT-savvy.
g. The product is offered as a free online service.

(a)(c)(d)(f)(g)

Explanation: (b) are (e) are functions available for a specific user types. Therefore, they are functional requirements. (a), (c), (d), (f) and (g) are either constraints on functionality or constraints on how the project is done, both of which are considered non-functional requirements.

4 Wrap up v1.1

After all changes that can be merged before the milestone deadline have been merged, use git tag feature to tag the current version with the milestone v1.1 and push the tag to the team repo.

5 Draft a rough project plan

Decide which enhancements each member will do by v1.4. We realize that it will be hard for you to estimate the effort required for each feature as you are not very familiar with the code base yet. Nevertheless, come up with a project plan as per your best estimate; this plan can be revised at later stages. It is better to start with some plan rather than no plan at all. If in doubt, choose to do less than more; we don't expect you to deliver a lot of big features anyway.

Divide each of those features into two increments, to be released at v1.2, v1.3 (v1.4 omitted deliberately as a buffer). Each increment should deliver a end-user visible enhancement.

* Jake Woo: Profile photo feature
  * v1.2: show a place holder for photo, showing a generic default image
  * v1.3: can specify photo location if it is in local hard disk,
          show photo from local hard disk

Reflect the above plan in the issue tracker by assigning the corresponding issues (create new issues if necessary) to yourself and to the corresponding milestone. For example, the user story pertaining to the increment show a place holder for photo, showing a generic default image should be assigned to Jake and to milestone v1.2

6 start implementing a minimal version of your enhancement

While we do not require you to do functionality changes in v1.1, if you have time, start implementing the version of your feature to be delivered in v1.2. We recommend that you break your v1.2 feature down to even smaller increments.

tP: v1.1 [week 7]

1 Update project website: AboutUs, ContactUs, README