Skip to content

Commit

Permalink
Merge pull request #272 from AY2324S2-CS2103T-W12-3/developer-guide-a…
Browse files Browse the repository at this point in the history 
…ppendix

Update Developer Guide Appendix
  • Loading branch information
@yisiox
yisiox authored Apr 15, 2024
2 parents ca79bd1 + e7aab24 commit 271482d
Showing 1 changed file with 150 additions and 42 deletions.
192 changes: 150 additions & 42 deletions docs/DeveloperGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -409,10 +409,11 @@ _{Explain here how the data archiving feature will be implemented}_

**Target user profile**:

* logistics managers who have a need to manage a significant number of contacts
responsible for logistical assets
* prefer desktop apps over other types
* can type fast and prefers typing to other forms of input
* logistics managers
* has a need to keep track of a significant number of contacts and assets they are responsible for
* prefers desktop apps over other types
* prefers typing to other forms of input
* can type fast

**Value proposition**:

Expand All @@ -438,27 +439,28 @@ Therefore, the application aims to deliver the following:

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

| Priority | As a ... | I want to ... | So that I can ... |
|-----------|---------------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| `* * *` | user | add new contacts and assets | keep track of these details |
| `* * ` | user | add tags to contacts | categorize them according to my preferences and workflow |
| `* * *` | user | delete contacts | update the list if a contact is no longer needed |
| `* * *` | user | edit contacts and assets | change details without recreating contacts, as there are too many details to re-add |
| `* * *` | user | easily view my existing contacts from the GUI | visually find the contacts I'm looking for |
| `* * *` | user | easily list, filter and navigate contacts | access relevant information quickly |
| `* * *` | user | search contacts by any category (e.g. name, asset, etc.) | easily find the relevant contact |
| Priority | As a ... | I want to ... | So that I can ... |
|-----------|---------------|------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| `* * *` | user | add new contacts and assets | keep track of these details |
| `* * *` | user | delete contacts | update the list if a contact is no longer needed |
| `* * *` | user | edit contacts and assets | change details without recreating contacts, as there are too many details to re-add |
| `* * *` | user | easily view my existing contacts from the GUI | visually find the contacts I'm looking for |
| `* * *` | user | list all contacts | view all contacts at a glance |
| `* * *` | user | search contacts by any category (e.g. name, asset, etc.) | easily find the relevant contact |
| `* * *` | user | see usage instructions | refer to instructions and examples when I forget how to use certain commands |
| `* * ` | user | add tags to contacts | categorize them according to my preferences and workflow |
| `* *` | user | quickly paste contact information (e.g. email) onto the clipboard | use the contact information immediately after finding it |
| `* *` | new user | view a drop-down suggestion of commands | efficiently navigate and utilize the app without extensive prior knowledge |
| `* *` | user | see no advertisements | not be distracted from my tasks |
| `* *` | user | add secondary personnel associated with an asset | have a backup contact if the main person is unreachable |
| `* *` | user | toggle between light/dark theme | customize the app to my preferences |
| `* *` | user | resize the app’s window | easily use multiple apps at once |
| `* *` | user | change the profile picture of each contact | easily identify them |
| `* *` | user | easily search within the system even if I mistype a few words | more easily locate relevant information |
| `* *` | hurried user | have commands even with extra whitespaces accepted | not waste time retyping commands |
| `* *` | advanced user | type shorter commands | type commands faster |
| `* *` | advanced user | use keyboard shortcuts | use the app more efficiently |
| `*` | advanced user | add custom fields | add more information to contacts |
| `* *` | user | see no advertisements | not be distracted from my tasks |
| `* *` | user | add secondary personnel associated with an asset | have a backup contact if the main person is unreachable |
| `* *` | user | toggle between light/dark theme | customize the app to my preferences |
| `* *` | user | resize the app’s window | easily use multiple apps at once |
| `* *` | user | change the profile picture of each contact | easily identify them |
| `* *` | user | easily search within the system even if I mistype a few words | more easily locate relevant information |
| `* *` | new user | view a drop-down suggestion of commands | efficiently navigate and utilize the app without extensive prior knowledge |
| `* *` | hurried user | have commands even with extra whitespaces accepted | not waste time retyping commands |
| `* *` | advanced user | type shorter commands | type commands faster |
| `* *` | advanced user | use keyboard shortcuts | use the app more efficiently |
| `*` | advanced user | add custom fields | add more information to contacts |

---

Expand All @@ -470,7 +472,8 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
**MSS**
1. User requests to add a contact.
2. User specifies details of the contact.
3. AB adds the contact.<br>
3. AB adds the contact.
4. AB shows a success message and new contact details to the user.<br>
Use case ends.

**Extensions**
Expand All @@ -486,7 +489,8 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
**Use case: UC2 - List contacts**
**MSS**
1. User requests to list contacts.
2. AB displays all contacts.<br>
2. AB displays all contacts.
3. AB shows a success message to the user.<br>
Use case ends.

--- {.dotted}
Expand All @@ -495,7 +499,8 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
**MSS**
1. User requests to search contacts.
2. User specifies details to search by.
3. AB displays all matching contacts.<br>
3. AB displays all matching contacts.
4. AB shows a success message and number of matching users to the user.<br>
Use case ends.

**Extensions**
Expand All @@ -513,7 +518,8 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
1. User !!lists contacts(UC2)!!.
2. User requests to edit a contact.
3. User specifies the index of the contact and details to edit.
4. AB updates the contact.<br>
4. AB updates the contact.
5. AB shows a success message and the new contact details to the user.<br>
Use case ends.

**Extensions**
Expand All @@ -528,16 +534,37 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli

--- {.dotted}

**Use case: UC5 - Delete contact**
**Use case: UC5 - Edit assets**
**MSS**
1. User requests to edit an asset.
2. User specifies the old and new name for the asset.
3. AB updates all relevant assets.
4. AB shows a success message and the new asset details to the user.<br>
Use case ends.

**Extensions**

<div class="step">2a. AB detects user input is invalid.</div>
<div class="sub-step">2a1. AB displays an error message.</div>
<div class="sub-step">2a2. User enters new input.</div>
<div class="sub-step">Steps 2a1-2a2 are repeated until user input is valid.</div>
<div class="sub-step">Use case resumes from step 3.</div>

--- {.dotted}

**Use case: UC6 - Delete contact**
**MSS**
1. User !!lists contacts(UC2)!!.
2. User requests to delete a contact.
3. User specifies the index of the contact to delete.
4. AB deletes the contact.<br>
4. AB deletes the contact.
5. AB shows a success message and the deleted contact details to the user.<br>
Use case ends.

**Extensions**

<div class="step">1a. AB displays no contacts.</div>
<div class="sub-step">Use case ends.</div>
<div class="step">3a. AB detects user input is invalid.</div>
<div class="sub-step">3a1. AB displays an error message.</div>
<div class="sub-step">3a2. User enters new input.</div>
Expand All @@ -546,7 +573,64 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli

--- {.dotted}

**Use case: UC6 - Add person to json file directly**
**Use case: UC7 - Undo command**
**MSS**
1. User requests to undo a command.
2. AB undoes the previous command.
3. AB shows a success message to the user.<br>
Use case ends.

**Extensions**

<div class="step">1a. AB detects user input is invalid.</div>
<div class="sub-step">1a1. AB displays an error message.</div>
<div class="sub-step">1a2. User enters new input.</div>
<div class="sub-step">Steps 1a1-1a2 are repeated until user input is valid.</div>
<div class="sub-step">Use case resumes from step 2.</div>
<div class="step">1b. AB detects there is no previous command to undo.</div>
<div class="sub-step">1b1. AB lets the user know there is no command to undo.</div>
<div class="sub-step">Use case ends.</div>

--- {.dotted}

**Use case: UC8 - Redo undo command**
**MSS**
1. User requests to redo an undo command.
2. AB redoes the command previously undone-ed.
3. AB shows a success message to the user.<br>
Use case ends.

**Extensions**

<div class="step">1a. AB detects user input is invalid.</div>
<div class="sub-step">1a1. AB displays an error message.</div>
<div class="sub-step">1a2. User enters new input.</div>
<div class="sub-step">Steps 1a1-1a2 are repeated until user input is valid.</div>
<div class="sub-step">Use case resumes from step 2.</div>
<div class="step">1b. AB detects there is no previous undo command to redo.</div>
<div class="sub-step">1b1. AB lets the user know there is no undo command to redo.</div>
<div class="sub-step">Use case ends.</div>

--- {.dotted}

**Use case: UC9 - Clear all contacts**
**MSS**
1. User requests to clear all contact data.
2. AB clears all contact data.
3. AB shows a success message to the user.<br>
Use case ends.

**Extensions**

<div class="step">1a. AB detects user input is invalid.</div>
<div class="sub-step">1a1. AB displays an error message.</div>
<div class="sub-step">1a2. User enters new input.</div>
<div class="sub-step">Steps 1a1-1a2 are repeated until user input is valid.</div>
<div class="sub-step">Use case resumes from step 2.</div>

--- {.dotted}

**Use case: UC10 - Add person to json file directly**
**MSS**
1. User adds a new person to the json file.
2. User runs the application.
Expand All @@ -568,6 +652,7 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
1. Majority of the target users are likely to find the app worth using.
1. Users with above average typing speed 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.
1. Features should fit together cohesively.
1. Should be easy and intuitive for users to use, even for users with limited technical knowledge.

#### Codebase
1. Must follow CS2103/T coding standards and code quality guidelines.
Expand Down Expand Up @@ -610,6 +695,7 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli

### Glossary

* **AddressBook**: The underlying system that AssetBook is built on
* **Asset**: An item of logistical significance, may be amenities or inventory
* **Clipboard**: The computer's storage for data that is copied and that will be produced by the paste command
* **Command**: Text that a user inputs to interact with the application
Expand Down Expand Up @@ -638,9 +724,10 @@ testers are expected to do more *exploratory* testing.

1. Initial launch

1. Download the jar file and copy into an empty folder
1. Download the jar file and copy into an empty folder.

1. Double-click the jar file Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.
1. Double-click the jar file.<br>
Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.

1. Saving window preferences

Expand All @@ -649,11 +736,22 @@ testers are expected to do more *exploratory* testing.
1. Re-launch the app by double-clicking the jar file.<br>
Expected: The most recent window size and location is retained.

1. _{ more test cases ... }_
### Adding a contact

1. Adding a contact

1. Test case: `add n\John Doe p\98765432 e\[email protected] a\311, Clementi Ave 2, #02-25 t\friends t\owesMoney A\screwdriver`<br>
Expected: AssetBook displays a success message, and the newly added contact's details are shown.

1. Test case: `add n\John Doe`<br>
Expected: AssetBook displays an error stating invalid command format, and no contact is added.

1. Other incorrect `add` commands to try: `add n\ p\ e\ a\311, Clementi Ave 2, #02-25 t\friends t\owesMoney A\screwdriver` <br>
Expected: Similar to previous.

### Deleting a person
### Deleting a contact

1. Deleting a person while all persons are being shown
1. Deleting a contact while all contacts are being shown

1. Prerequisites: List all persons using the `list` command. Multiple persons in the list.

Expand All @@ -663,16 +761,26 @@ testers are expected to do more *exploratory* testing.
1. Test case: `delete 0`<br>
Expected: No person is deleted. Error details shown in the status message. Status bar remains the same.

1. Other incorrect delete commands to try: `delete`, `delete x`, `...` (where x is larger than the list size)<br>
1. Other incorrect `delete` commands to try: `delete`, `delete x`, `...` (where x is larger than the list size)<br>
Expected: Similar to previous.

1. _{ more test cases ... }_

### Saving data

1. Dealing with missing/corrupted data files

1. _{explain how to simulate a missing/corrupted file, and the expected behavior}_
</li>
1. Modify or delete data files.

1. Open AssetBook. If AssetBook is open, close and reopen it.<br>
Expected: AssetBook will detect missing/corrupted data files, show a warning to the user about the missing/corrupted data files, and start with an empty list.

--------------------------------------------------------------------------------------------------------------------

## **Appendix: Planned Enhancements**

1. _{ more test cases ... }_
1. **Feature Flaw** - Currently, `redo` and `undo` commands only display a success message without any additional information. In future versions, we will display the specific commands undone or redone.
2. **Feature Flaw** - Currently, using the `copy` command on assets and tags will come with the square brackets associated with the list data structure, which are redundant for the users. In future versions, we will remove these square brackets when copying tags and assets.
3. **Feature Flaw** - Currently, using the `find` command searches across all contact details, and hence searching `bell` will return contacts with the name including `bell` and contacts with assets including `bell`, which can be confusing. In future versions, we will have specific commands to find contacts and assets separately.
4. **Feature Flaw** - Currently, additional details cannot be added to assets, such as specifications, locations and so on. In future versions, more details can be added to assets to make the app easier to use for users.
5. **Feature Flaw** - Currently, using the `add` command for contacts with the same name is not allowed, but there can exist multiple people with the same name. In future versions, we will improve duplicate person detection and allow multiple contacts with the same name.
6. **Feature Flaw** - Currently, tags and assets have a very similar color scheme, which makes it hard to differentiate for users. In future versions, we will add more visual clarity tags and assets.
7. **Feature Flaw** - Currently, the error message display for duplicate asset names in the `asset` command is inaccruate to the actual problem. In future versions, we will modify the error message specifically for this case.

0 comments on commit 271482d

Please sign in to comment.