Skip to content

Commit

Permalink
Merge pull request #262 from AY2425S1-CS2103T-T08-2/final-ug-changes
Browse files Browse the repository at this point in the history 
Final UG changes
  • Loading branch information
@dwsc37
dwsc37 authored Nov 11, 2024
2 parents 5834a23 + 30eabf3 commit 452951d
Show file tree
Hide file tree
Showing 2 changed files with 111 additions and 61 deletions.
106 changes: 57 additions & 49 deletions docs/DeveloperGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ The **API** of this component is specified in [`Ui.java`](https://github.com/AY2

<puml src="diagrams/UiClassDiagram.puml" alt="Structure of the UI Component"/>

The UI consists of a `MainWindow` that is made up of parts e.g.`CommandBox`, `ResultDisplay`, `PersonListPanel`, `StatusBarFooter` etc. All these, including the `MainWindow`, inherit from the abstract `UiPart` class which captures the commonalities between classes that represent parts of the visible GUI.
The UI consists of a `MainWindow` that is made up of parts e.g.`CommandBox`, `ResultDisplay`, `StudentListPanel`, `StatusBarFooter` etc. All these, including the `MainWindow`, inherit from the abstract `UiPart` class which captures the commonalities between classes that represent parts of the visible GUI.

The `UI` component uses the JavaFx UI framework. The layout of these UI parts are defined in matching `.fxml` files that are in the `src/main/resources/view` folder. For example, the layout of the [`MainWindow`](https://github.com/AY2425S1-CS2103T-T08-2/tp/tree/master/src/main/java/keycontacts/ui/MainWindow.java) is specified in [`MainWindow.fxml`](https://github.com/AY2425S1-CS2103T-T08-2/tp/tree/master/src/main/resources/view/MainWindow.fxml)

Expand Down Expand Up @@ -112,7 +112,7 @@ How the `Logic` component works:

1. When `Logic` is called upon to execute a command, it is passed to an `KeyContactsParser` object which in turn creates a parser that matches the command (e.g., `DeleteCommandParser`) and uses it to parse the command.
1. This results in a `Command` object (more precisely, an object of one of its subclasses e.g., `DeleteCommand`) which is executed by the `LogicManager`.
1. The command can communicate with the `Model` when it is executed (e.g. to delete a person).<br>
1. The command can communicate with the `Model` when it is executed (e.g. to delete a student).<br>
Note that although this is shown as a single step in the diagram above (for simplicity), in the code it can take several interactions (between the command object and the `Model`) to achieve.
1. The result of the command execution is encapsulated as a `CommandResult` object which is returned back from `Logic`.

Expand Down Expand Up @@ -146,7 +146,7 @@ The `Model` component,

**API** : [`Storage.java`](https://github.com/AY2425S1-CS2103T-T08-2/tp/tree/master/src/main/java/keycontacts/storage/Storage.java)

<puml src="diagrams/StorageClassDiagram.puml" width="900" />
<puml src="diagrams/StorageClassDiagram.puml" width="1200" />

The `Storage` component,
* can save both student directory data and user preference data in JSON format, and read them back into corresponding objects.
Expand Down Expand Up @@ -184,11 +184,11 @@ Step 1. The user launches the application. The `VersionedStudentDirectory` will

<puml src="diagrams/UndoRedoState0.puml" alt="UndoRedoState0" />

Step 2. The user executes `delete 5` command to delete the 5th person in the student directory. The `delete` calls `Model#commitStudentDirectory()`, causing the modified state of the student directory after the `delete 5` command executes to be saved in the `studentDirectoryStateList`, and the `currentStatePointer` is shifted to the newly inserted student directory state.
Step 2. The user executes `delete 5` command to delete the 5th student in the student directory. The `delete` calls `Model#commitStudentDirectory()`, causing the modified state of the student directory after the `delete 5` command executes to be saved in the `studentDirectoryStateList`, and the `currentStatePointer` is shifted to the newly inserted student directory state.

<puml src="diagrams/UndoRedoState1.puml" alt="UndoRedoState1" />

Step 3. The user executes `add n/David …​` to add a new person. The `add` command calls `Model#commitStudentDirectory()`, causing another modified student directory state to be saved into the `studentDirectoryStateList`.
Step 3. The user executes `add n/David …​` to add a new student. The `add` command calls `Model#commitStudentDirectory()`, causing another modified student directory state to be saved into the `studentDirectoryStateList`.

<puml src="diagrams/UndoRedoState2.puml" alt="UndoRedoState2" />

Expand All @@ -200,7 +200,7 @@ Step 3. The user executes `add n/David …​` to add a new person. The `add` co

<div style="page-break-after: always;"></div>

Step 4. The user now decides that adding the person was a mistake, and decides to undo that action by executing the `undo` command. The `undo` command will call `Model#undoStudentDirectory()`, which will shift the `currentStatePointer` once to the left, pointing it to the previous student directory state, and restores the student directory to that state.
Step 4. The user now decides that adding the student was a mistake, and decides to undo that action by executing the `undo` command. The `undo` command will call `Model#undoStudentDirectory()`, which will shift the `currentStatePointer` once to the left, pointing it to the previous student directory state, and restores the student directory to that state.

<puml src="diagrams/UndoRedoState3.puml" alt="UndoRedoState3" />

Expand Down Expand Up @@ -258,7 +258,7 @@ The following activity diagram summarizes what happens when a user executes a ne

* **Alternative:** Individual command knows how to undo/redo by
itself.
* Pros: Will use less memory (e.g. for `delete`, just save the person being deleted).
* Pros: Will use less memory (e.g. for `delete`, just save the student being deleted).
* Cons: We must ensure that the implementation of each individual command are correct.

--------------------------------------------------------------------------------------------------------------------
Expand Down Expand Up @@ -290,9 +290,9 @@ The following activity diagram summarizes what happens when a user executes a ne
* is reasonably comfortable using CLI apps

**Value proposition**:
* Manage students' schedules faster than a typical mouse/GUI driven app
* Manage students' information and schedules faster than a typical mouse/GUI driven app
* Accommodate students who need to reschedule, making for a flexible scheduling tool
* Track students' learning over time, enabling piano teachers to monitor students' grade and progress on piano pieces
* Display grade level and piano pieces, enabling piano teachers to prepare for lessons.

<br>
<br>
Expand All @@ -301,38 +301,38 @@ The following activity diagram summarizes what happens when a user executes a ne

Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unlikely to have) - `*`

| Priority | As a …​ | I want to …​ | So that I can…​ |
|----------|------------------|-------------------------------------------------------------|----------------------------------------------|
| `* * *` | user | cancel a particular lesson session | respond to special circumstances effectively |
| `* * *` | user | schedule a make-up lesson for students who missed | manage lesson rescheduling efficiently |
| `* * *` | user | save a student’s lesson timing | know when I will meet them |
| `* * *` | user | save the data and retrieve them after restarting the app | ensure my data is persistent |
| `* * *` | user | view a list of all my students | keep track of all my students |
| `* * *` | user | delete a student when they stop taking lessons | keep my records clean |
| `* * *` | new user | view the list of commands | know what commands I can run |
| `* * *` | user | add a piano piece to a student | track what piece they are working on |
| `* * *` | user | save a student’s address | know where to travel for tutoring |
| `* * *` | user | see the grade level of a student | tailor the lesson to their proficiency |
| `* * *` | user | save a person's contact | contact them easily for tutoring |
| `* * *` | user | undo my last command | revert the effects of a wrong command |
| `* * *` | user | redo a command that I undid | revert the effects of a wrong undo |
| `* *` | user | modify the details of each record | change particulars when needed |
| `* *` | user | sort the record by student name, lesson day, contact, etc. | find specific records easily |
| `* *` | user | see students scheduled for a particular day | know my schedule for the day |
| `* *` | user | search students based on name, day of lesson, or category | locate a student efficiently |
| Priority | As a …​ | I want to …​ | So that I can…​ |
|----------|------------------|-------------------------------------------------------------|---------------------------------------------|
| `* * *` | user | cancel a particular lesson session | account for student availability |
| `* * *` | user | schedule a make-up lesson for students who missed | manage lesson rescheduling efficiently |
| `* * *` | user | save a student’s lesson timing | know when I will meet them |
| `* * *` | user | save the data and retrieve them after restarting the app | ensure my data is persistent |
| `* * *` | user | view a list of all my students | keep track of all my students |
| `* * *` | user | delete a student when they stop taking lessons | keep my records clean |
| `* * *` | new user | view the list of commands | know what commands I can run |
| `* * *` | user | add a piano piece to a student | track what piece they are working on |
| `* * *` | user | save a student’s address | know where to travel for tutoring |
| `* * *` | user | see the grade level of a student | tailor the lesson to their proficiency |
| `* * *` | user | save a student's contact | easily contact them for tutoring |
| `* * *` | user | undo my last command | revert the effects of a wrong command |
| `* * *` | user | redo a command that I undid | revert the effects of a wrong undo |
| `* *` | user | modify the details of each record | change particulars when needed |
| `* *` | user | sort the record by student name, lesson day, contact, etc. | find specific records easily |
| `* *` | user | see students scheduled for a particular day | know my schedule for the day |
| `* *` | user | search students based on name, day of lesson, or category | locate a student efficiently |
| `* *` | user | export my student data to a CSV file | back up my records or share them with others |
| `*` | user | track the purchase and sale of learning materials | manage inventory and ensure reimbursement |
| `*` | user | generate reports on each student’s progress | share them with parents or guardians |
| `*` | user | view a timetable for the week | prepare my schedule |
| `*` | new user | receive prompts/suggestions when I type a command wrongly | get help using the system |
| `*` | experienced user | use shortcuts/aliases for commands | perform common tasks faster |
| `*` | user | group my students together if they are in the same class | view their information easier |
| `*` | user | track whether each student has paid for the month | collect my fees on time |
| `*` | user | keep track of how much each student should pay for lessons | manage fees easier |
| `*` | user | write down miscellaneous notes for each student | recall them before each lesson |
| `*` | user | view a summary of my income for the month | track my earnings |
| `*` | user | track attendance for each student | see how consistent they are with lessons |
| `*` | user | track the progress of each student on their assigned pieces | monitor their improvement |
| `*` | user | track the purchase and sale of learning materials | manage inventory and ensure reimbursement |
| `*` | user | generate reports on each student’s progress | share them with parents or guardians |
| `*` | user | view a timetable for the week | prepare my schedule |
| `*` | new user | receive prompts/suggestions when I type a command wrongly | get help using the system |
| `*` | experienced user | use shortcuts/aliases for commands | perform common tasks faster |
| `*` | user | group my students together if they are in the same class | view their information easier |
| `*` | user | track whether each student has paid for the month | collect my fees on time |
| `*` | user | keep track of how much each student should pay for lessons | manage fees easier |
| `*` | user | write down miscellaneous notes for each student | recall them before each lesson |
| `*` | user | view a summary of my income for the month | track my earnings |
| `*` | user | track attendance for each student | see how consistent they are with lessons |
| `*` | user | track the progress of each student on their assigned pieces | monitor their improvement |

<br>
<br>
Expand All @@ -358,8 +358,10 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
* Steps 1a1-1a2 are repeated until the data entered are correct.
* Use case resumes from step 2.

<br>

* 1b. KeyContacts detects an existing student that is a duplicate of the student the user is trying to add.
* 1b1. KeyContacts alerts the user that the student already exists
* 1b1. KeyContacts alerts the user that the student already exists.
* Use case ends.

---
Expand Down Expand Up @@ -422,12 +424,6 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli

Use case ends.

**Extensions**

* 1a. KeyContacts detects an error while retrieving the list.
* 1a1. KeyContacts shows an error message.
* Use case ends.

---

#### Use case: Find a student (UC06)
Expand Down Expand Up @@ -685,8 +681,8 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli

### Non-Functional Requirements

1. **Cross-Platform Compatibility**: Should work on any _mainstream OS_ as long as it has Java `17` or above installed.
2. **Performance**: Should be able to hold up to 100 persons without a noticeable sluggishness in performance for typical usage.
1. **Cross-Platform Compatibility**: Should work on Windows, MacOS and Linux as long as it has Java `17` or above installed.
2. **Performance**: Should be able to hold up to 100 students without a noticeable sluggishness in performance for typical usage.
3. **Optimised for CLI Users**: A user with above average typing speed (50 words per minute) for regular English text (i.e. not code, not system admin commands) should be able to accomplish most of the tasks faster using commands than using the mouse.
4. **CLI Responsiveness**: Commands executed through the CLI should respond within 1 second under normal load (e.g. with 100 contacts).
5. **UI Responsiveness**: The UI must remain responsive when updating large datasets, such as when displaying a list of contacts, without causing delays of more than 1 second in interactions.
Expand Down Expand Up @@ -912,6 +908,18 @@ testers are expected to do more *exploratory* testing.

7. **Improve calendar view to indicate if a regular lesson was cancelled for that week.** The calendar view currently has no indication of when a student's regular lesson is if it is cancelled on the week that is being viewed. This can cause confusion among the tutors as they may observe a clash with the lesson despite not seeing it in the schedule. The planned enhancement is to show all regular lessons but with an indication of its cancellation status.

<br>

8. **Increase minimum width of application.** Currently, the minimum width causes the group tag to be cut off. The planned enhancement is to increase this minimum size to a point that will not have this issue.

<br>

9. **Gracefully handle long group names.** Currently, a long group name will obscure the student's name. The planned enhancement is to restrict the group name to 20 characters long.

<br>

10. **Improve the clarity of the redo feature by specifying the command that was redone.** Currently, the redo command return result is unclear. The planned enhancement will be to include the command being redone in the redo command result.

---

## **Appendix: Effort**
Expand Down
Loading

0 comments on commit 452951d

Please sign in to comment.