From 8365c7642b723b334a156224b92513c1b2ce501b Mon Sep 17 00:00:00 2001 From: Han Bin Date: Thu, 3 Oct 2024 21:02:04 +0800 Subject: [PATCH] Fix formatting issues in DeveloperGuide.md Fix minor formatting issues in the Developer Guide. --- docs/DeveloperGuide.md | 559 ++++++++++++++++++++++++++++++++--------- 1 file changed, 436 insertions(+), 123 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index e70fbfbbbb9..995ad381117 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -13,7 +13,7 @@ ## **Acknowledgements** -_{ list here sources of all reused/adapted ideas, code, documentation, and third-party libraries -- include links to the original source as well }_ +This project is based on the AddressBook-Level3 project created by the [SE-EDU initiative](https://se-education.org). -------------------------------------------------------------------------------------------------------------------- @@ -287,24 +287,69 @@ _{Explain here how the data archiving feature will be implemented}_ ### User stories -Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unlikely to have) - `*` - -| Priority | As a …​ | I want to …​ | So that I can…​ | -|----------|--------------------------------------------|------------------------------|------------------------------------------------------------------------| -| `* * *` | new user | see usage instructions | refer to instructions when I forget how to use the App | -| `* * *` | user | add a new person | | -| `* * *` | user | delete a person | remove entries that I no longer need | -| `* * *` | user | find a person by name | locate details of persons without having to go through the entire list | -| `* *` | user | hide private contact details | minimize chance of someone else seeing them by accident | -| `*` | user with many persons in the address book | sort persons by name | locate a person easily | - -*{More to be added}* +Priorities: +High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unlikely to have) - `*` + +Those without any stars are user stories that were considered but will not be implemented at this time. + +| Priority | As a …​ | I want to …​ | So that…​ | +|:--------:|---------------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `* * *` | user | add tag(s) to each contact based on created tags such as florist, musician etc. | I can easily understand the group this person belongs to. | +| `* * *` | user | add a phone number associated with each contact | I can easily find the contact information for each contact. | +| `* * *` | user | add the address associated with each contact | I can easily find the address of each contact. | +| `* * *` | user | filter contacts by tag | I can quickly see all the groups under the same tag, and find the right vendor based on the type of services provided. | +| `* * *` | user | add new contacts into WedLinker | I can store the contact details of new contacts. | +| `* * *` | user | delete contacts that are no longer needed | I can remove unnecessary contacts and have a more organised address book. | +| `* * *` | user | search for contact by name | I can find specific contacts that I am looking for. | +| `* * *` | user | create tags | I can have special categories for non traditional vendors. | +| `* *` | user | edit information such as the contact number and address of each contact | all contacts have the most updated information. | +| `* *` | user | clear all the contacts in the system | I can clear all my contacts quickly without having to individually delete them if I want to add in a completely new set of contacts. | +| `* *` | careless user | receive a prompt that requires me to key in a confirmation that I want to delete a contact or clear the address book | I will not lose all my contacts when I accidentally type delete/ clear. | +| `* *` | user | assign each guest contact its dietary requirements status | I can track the dietary requirement of each guest. | +| `* *` | user | sort contacts by alphabetical order | I can easily find the contacts required in a large address book. | +| `* *` | user | assign additional information for each contact | I can include important notes that may not fit into other categories, such as reminders for what the contact might need. | +| `* *` | first-time user | see some sample contacts already available in the app | I can try out the different features without needing to add my own data (e.g allocating people to wedding, allocating task to contacts). | +| `* *` | careless, first-time user | reload the sample contacts into the app | I can continue trying out different features without needing to add my own data in case I accidentally cleared the contacts. | +| `* *` | first-time user | see a help message showing all the commands/feature I can use | I can try out all the different features by referring to the message. | +| `*` | user | assign tasks to contacts | I can track which tasks have been assigned to each contact. | +| `*` | user | update the status of tasks of contacts | I can track the status of completion of the tasks assigned to contacts. | +| `*` | user | add a tag to each guest indicating their table number | track the table each guest is seated at. | +| `*` | user | key in the table number and get the list of guests seated at that table | I can quickly identify all the groups seated at one table. | +| `*` | user | assign a rating out of 5 to each vendor | I can track the experience with this vendor for future reference. | +| `*` | busy user | add multiple wedding events | I can track contacts for multiple weddings at once. | +| `*` | busy user | tag each contact to a wedding | I can easily see which contacts are relevant to which wedding. | +| `*` | user | assign dates to a wedding | I can keep track of when different weddings are scheduled. | +| `*` | user | assign dates to a wedding | I can keep track of when different weddings are scheduled. | +| `*` | user | filter contacts by wedding | I can keep track of which contacts are relevant for each wedding. | +| `*` | user | send out (standardised formatted) information (text/email) from the application | I can efficiently send out information without any mistakes. | +| `*` | user | share the contact details to relevant third-parties for bookings (eg: venue bookings, suit/dress rental, etc.) | I can easily send out all relevant information (including dietary restriction, and other tags) to all the third-parties. | +| `*` | user | exclude tags from search and filter | I can focus on contacts that are relevant to certain events or requirements without being overwhelmed by unnecessary information. | +| `*` | busy user | autocomplete existing tags when user is inputting tag information | I can quickly assign roles for people that might be working with others I have already input into the system and not have to type the same roles in multiple times. | +| `*` | user | assign availability to vendors | I can check who will be available for a particular wedding. | +| `*` | user | filter availability of vendors | I can easily find vendors that can cater to a wedding. | +| `*` | user | store multiple contact methods | I can contact the vendors through different means. | +| `*` | user | re-assign tasks to another contact | I can account for vendors suddenly being unavailable. | +| `*` | user | set reminders for tasks to different contacts | I can easily track and follow up with clients and vendors for deliverables. | +| `*` | user | see a list of all tasks and reminders I have assigned to contacts in its own window | I can quickly and easily see what my earliest priorities are and act on them quickly. | +| `*` | user | see a calendar view of tasks, reminders, and weddings I have assigned | I can see the whole timelines of my planned weddings and see how much time there is between tasks. | +| `*` | user | set privacy setting for different contacts | I can keep personal and sensitive information private when sharing address book. | +| `*` | forgetful user | create links between different contacts, such as assigning a vendor to a bride or groom in a wedding | I can easily navigate from key stakeholders in the wedding that I remember better to vendors who I might not remember as well. | +| `*` | user | add certain vendors as favorites | I can remember which vendors performed well and see if they are favorites. | +| `*` | user | access a list of all my favorite vendors | I can easily check who the best vendors were that I previously engaged with. | +| | user | generate a checklist of all the contacts for a particular wedding, grouped by roles | I can keep track of who is meant to be present at the wedding. | +| | user | assign a time for each contact for when they are meant to arrive | I can easily keep track of which people are on time and check who to contact in case they have not arrived yet. | +| | user | attach extra documents as a file to various contacts | I can store all the information in one place, eg. Invoices from a vendor. | +| | user | categorize tasks based on its nature (e.g. procurement, arrangement) | I can view tasks in a more organised manner. | ### Use cases -(For all use cases below, the **System** is the `WedLinker` and the **Actor** is the `User`, unless specified otherwise) +(For all use cases below, the **System** is the `WedLinker` and the **Actor** is the `user`, unless specified otherwise) -**Use case: UC01 - List all contacts** +> Use Cases beginning with 'UC' cover core AddressBook functionality. +> +> Use Cases beginning with 'UCSH' cover non-core AddressBook functionality. + +**Use case: UC01 List all Contacts** **MSS** @@ -315,11 +360,11 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli -**Use case: UC02 - Add a contact** +**Use case: UC02 Add a Contact** **MSS** -1. User issues the add-contact command with the corresponding details. +1. User requests to add contact with the corresponding details. 2. The system adds the contact and displays a success message. 3. The system shows the new contact in the address book. @@ -329,55 +374,54 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli * 1a. The system detects a name input error (duplicated or trailing whitespace). * 1a1. The system displays an error message. - - Use case ends. - - -* 1b. The system detects a phone number input error (invalid format): + + Use case ends. + + +* 1b. The system detects a phone number input error (invalid format). * 1b1. The system displays an error message stating the correct format. - - Use case ends. - - -* 1c. The system detects an address input error (too long): + + Use case ends. + + +* 1c. The system detects an address input error (too long). * 1c1. The system displays an error message stating the maximum length. - - Use case ends. - - -* 1d. The system detects an email input error (invalid format): + + Use case ends. + + +* 1d. The system detects an email input error (invalid format). * 1d1. The system displays an error message stating the correct format. - - Use case ends. - - -* 1e. The system detects a duplicate phone number error: + + Use case ends. + + +* 1e. The system detects a duplicate phone number error. * 1e1. The system displays an error message mentioning the existence of a duplicate phone number. - - Use case ends. - -* 1f. The system detects an invalid tag input: + Use case ends. + + +* 1f. The system detects an invalid tag input. * 1f1. The system displays an error message stating the tag is invalid. - - Use case ends. + + Use case ends. -**Use case: UC03 - Add Phone Number to Contact** +**Use case: UC03 Add Phone Number to Contact** **Guarantees:** * No duplicate phone numbers will be stored in two different contacts. - **MSS** 1. User lists all contacts (UC01). -2. User issues the add-phone command with the corresponding details. +2. User requests to add phone number for a contact with the corresponding details. 3. The system adds the phone number to the contact and displays a success message. 4. The system displays the updated contact information in the address book. - Use case ends. + Use case ends. **Extensions** @@ -386,188 +430,457 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli Use case ends. -* 2a. The system detects an invalid contact index: +* 2a. The system detects an invalid contact index. * 2a1. The system displays an error message stating the contact index is invalid. - Use case resumes at step 2. - - -* 2b. The system detects a phone number input error (invalid format): + Use case resumes at step 1. + + +* 2b. The system detects a phone number input error (invalid format). * 2b1. The system displays an error message stating the correct format. - - Use case resumes at step 2. - -* 2c. The system detects a duplicate phone number error: + Use case resumes at step 1. + + +* 2c. The system detects a duplicate phone number error. * 2c1. The system displays an error message mentioning the existence of a duplicate phone number. - - Use case resumes at step 2. + + Use case resumes at step 1. -**Use case: UC04 - Add Address to Contact** +**Use case: UC04 Add Address to Contact** **MSS** 1. User lists all contacts (UC01). -2. User issues the add-address command with the corresponding details. -3. The system adds the address to the contact and displays a success message +2. User requests to add address for a contact with the corresponding details. +3. The system adds the address to the contact and displays a success message. 4. The system displays the updated contact information in the address book. - Use case ends. + Use case ends. **Extensions** * 1a. The list is empty. - Use case ends. + Use case ends. -* 2a. The system detects an invalid contact index: +* 2a. The system detects an invalid contact index. * 2a1. The system displays an error message stating the contact index is invalid. - Use case resumes at step 2. - + Use case resumes at step 1. + -* 2b. The system detects an address input error (too long): - * 2b1. The system displays an error message stating the maximum length +* 2b. The system detects an address input error (too long). + * 2b1. The system displays an error message stating the maximum length. - Use case resumes at step 2. + Use case resumes at step 1. -**Use case: UC05 - Add Email to Contact** +**Use case: UC05 Add Email to Contact** **MSS** 1. User lists all contacts (UC01). -2. User issues the add-email command with the corresponding details. -3. The system adds the email address to the contact and displays a success message +2. User requests to add email address for a contact with the corresponding details. +3. The system adds the email address to the contact and displays a success message. 4. The system displays the updated contact information in the address book. - Use case ends. + Use case ends. **Extensions** * 1a. The list is empty. Use case ends. - -* 2a. The system detects an invalid contact index: + + +* 2a. The system detects an invalid contact index. * 2a1. The system displays an error message stating the contact index is invalid. - Use case resumes at step 2. + Use case resumes at step 1. -* 2b. The system detects an email input error (invalid format): +* 2b. The system detects an email input error (invalid format). * 2b1. The system displays an error message stating the correct format. - - Use case resumes at step 2. - - **Use case: UC06 Search for contacts by Name** + + Use case resumes at step 1. + + + +**Use case: UC06 Search for Contacts by Name** **MSS** 1. User searches for the contact by name. -2. WedLinker shows a list of contacts containing the name. +2. System shows a list of contacts containing the name. + + Use case ends. + + **Use case: UC07 Filter by Tag** **MSS** 1. User filters for contacts with a specified tag. -2. WedLinker only shows a list of contact with the specified tag. +2. System only shows a list of contact with the specified tag. Use case ends. **Extensions** -* 2a. The list is empty. +* 1a. The list is empty. Use case ends. + + **Use case: UC08 Create Tags** **MSS** -1. User creates a tag. -2. WedLinker displays the successful creation of tag. +1. User requests to create a tag. +2. System displays the successful creation of tag. Use case ends. **Extensions** -* 2a. The tag already exists. - * 2a1. WedLinker does not create a new tag. - * 2a2. WedLinker informs the user the tag already exists. +* 1a. The tag already exists. + * 1a1. System does not create a new tag. + * 1a2. System informs the user the tag already exists. + + Use case ends. + - Use case ends. **Use case: UC09 Tagging a contact with a specified tag** **MSS** -1. User searches for the contact to be tagged (UC06). -2. WedLinker shows a list of contacts for the search. -3. User adds the tag to the contact based on the index of the list. -4. WedLinker informs the user the contact is tagged. -5. WedLinker shows the user the final result of the contact. +1. User lists all contacts (UC01). +2. User adds the tag to the contact. +3. System informs the user the contact is tagged. +4. System shows the user the final result of the contact. Use case ends. **Extensions** -* 2a. The list is empty. +* 1a. The list is empty. Use case ends. -* 3a. WedLinker detects that the tag does not exist. +* 2a. System detects that the tag does not exist. + + * 2a1. System creates a new tag (UC08). + + Use case resumes at step 3. + +* 2b. The given index is invalid. - * 3a1. WedLinker creates a new tag (UC08) + * 2b1. System shows an error message prompting the user to enter a valid index. - Use case resumes at step 4 + Use case resumes at step 1. -* 3b. The given index is invalid. - * 3b1. WedLinker shows an error message prompting the user to enter a valid index. **Use case: UC10 Delete Contact** **MSS** -1. WedLinker shows a list of contacts containing the name (UC01). -2. User requests to delete a specific person in the list based on the index. -3. WedLinker deletes the contact. +1. User lists all contacts (UC01). +2. User requests to delete a specific person in the list. +3. System deletes the contact. Use case ends. **Extensions** -* 2a. The list is empty. +* 1a. The list is empty. Use case ends. -* 4a. The given index is invalid. - * 4a1. WedLinker shows an error message prompting the user to enter a valid index. +* 2a. The given index is invalid. + + * 2a1. System shows an error message prompting the user to enter a valid index. + + Use case resumes at step 1. + + + +**Use case: UCSH01 Edit details for a contact** + +**MSS** + +1. User lists all contacts (UC01). +2. User requests to edit the details of a person and specifies what they want to change the details to. +3. AddressBook changes the existing details to the specified details and shows list of persons with new details. + +**Extensions** + +* 1a. The list is empty. + + Use case ends. + + +* 2a. The given index is invalid. + + * 2a1. System shows an error message prompting the user to put in a valid index. + + Use case resumes at step 1. + + +* 2b. The user does not specify what type of details they want to change. + + * 2b1. System shows an error message prompting the user to put in the type of details they want to edit. + + Use case resumes at step 1. + + +* 2c. The user does not specify what the new details should be. - Use case resumes at step 2. + * 2c1. System shows an error message prompting the user to put in the new details. + + Use case resumes at step 1. + + +* 2d. The user specifies details that do not meet the requirements of the detail type. + + * 2d1. System shows an error message prompting the user with the correct detail type format and requirements. + + Use case resumes at step 1. + + + +**Use case: UCSH02 Clear all contacts from the system** + +**Guarantees:** +* No persons will be left in the system. + +**MSS** + +1. User requests to clear all contact. +2. System deletes all contacts and shows a blank list of persons. + + Use case ends. + +**Use case: UCSH03 Receive a prompt when deleting a contact** + +**MSS** + +1. User lists all contacts (UC01). +2. User requests to delete a contact. +3. System gives a prompt to confirm whether the user wants to delete the contact. +4. User confirms they want to delete the contact. +5. System deletes the contact and shows the updated list of persons. + + Use case ends. + +**Extensions** + +* 1a. The list is empty. + + Use case ends. + + +* 2a. The given index is invalid. + + * 2a1. System shows an error message prompting the user to put in a valid index. + + Use case resumes at step 1. + + +* 3a. User says they do not want to delete the contact. + + * 3a1. System shows a message indicating the contact was not deleted. + + Use case ends. + + + +**Use case: UCSH04 Receive a prompt when clearing the system** + +**MSS** + +1. User requests to clear the system of all persons. +2. System gives a prompt to confirm whether the user wants to clear all contacts. +3. User confirms they want to clear all contacts. +4. System deletes all contacts and shows a blank list of persons. + + Use case ends. + +**Extensions** + +* 2a. User says they do not want to clear all their contacts. + + * 2a1. System shows a message indicating the system was not cleared. + + Use case ends. + + + +**Use case: UCSH05 Assign dietary requirement to contact** + +**MSS** + +1. User lists all contacts (UC01). +2. User requests to add a dietary status to the person. +3. System adds the dietary status to the contact and shows list of persons with new details. + Use case ends. + +**Extensions** + +* 1a. The list is empty. + Use case ends. + + +* 2a. The given index is invalid. + + * 2a1. System shows an error message prompting the user to put in a valid index. + + Use case resumes at step 1. + + + +**Use case: UCSH06 Sort contacts in alphabetical order** + +**MSS** + +1. User requests to show a list of persons sorted alphabetically. +2. System shows the list of persons sorted in alphabetical order. + + Use case ends. + +**Extensions** + +* 1a. The list is empty. + + Use case ends. + + + +**Use case: UCSH07 Add additional information for a person** + +**MSS** + +1. User lists all contacts (UC01). +2. User requests to add additional information for a person. +3. System adds the additional information to the contact and shows list of persons with new details. + + Use case ends. + +**Extensions** + +* 1a. The list is empty. + + Use case ends. + + +* 2a. The given index is invalid. + + * 2a1. System shows an error message prompting the user to put in a valid index. + + Use case resumes at step 1. + + +* 2a. The additional information is blank. + + * 2a1. System shows an error message prompting the user to type in the additional information. + + Use case resumes at step 1. + + +**Use case: UCSH08 See sample contacts in the system before starting to modify it** + +Preconditions: User has not added or edited contacts previously. + +**MSS** + +1. User opens the application. +2. System shows a list of sample contacts. + + Use case ends. + + + +**Use case: UCSH09 Reload sample contacts in the system** + +**MSS** + +1. User requests to reload sample contacts into the system. +2. System deletes all current persons in the system and shows a list of sample contacts. + + Use case ends. + + + +**Use case: UCSH10 See a list of all possible commands** + +**MSS** + +1. User requests to see a list of all possible commands they can use in the system. +2. System shows a list of commands with their corresponding input format. + + Use case ends. -*{More to be added}* ### Non-Functional Requirements -1. Should work on any _mainstream OS_ as long as it has Java `17` or above installed. -2. Should be able to hold up to 1000 persons without a noticeable sluggishness in performance for typical usage. -3. A user 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. +**Performance Requirements** +- P1: The system should be able to hold up to 1000 persons without noticeable sluggishness in performance for typical usage. +- P2: The application should respond within two seconds for most user operations. + +**Usability Requirements** +- U1: A user with above-average typing speed for regular English text (not code, not system admin commands) should be able to accomplish most tasks faster using keyboard commands than using the mouse. +- U2: The application should target users who can type fast and prefer typing over other means of input, such as clicking buttons, selecting dropdowns and drag-and-drop means. +- U3: The GUI should provide clear and user-friendly error messages when operations fail to assist users in correcting mistakes. +- U4: The GUI should not cause any resolution-related inconveniences for standard screen resolutions of 1920x1080 and higher, and for screen scales of 100% and 125%. +- U5: The GUI should be usable for resolutions of 1280x720 and higher, and for screen scales of 150%. + +**Compatibility Requirements** +- C1: The application should work on any _mainstream OS_ as long as it has Java `17` or above installed. +- C2: The application should be platform-independent and work on Windows, Linux, and OS-X without relying on OS-dependent libraries or features. +- C3: The application should not depend on the developer’s own remote server. + +**Data Requirements** +- D1: The application should not use a Database Management System (DBMS) for data storage. +- D2: Data stored in the address book should be stored locally, in a human-editable text file. +- D2: The entire application should be packaged into a single JAR file. +- D3: The JAR file size should be within 100 MB and should not be unnecessarily bloated. +- D4: PDF documents generated for documentation should have a file size within 15 MB and should not be unnecessarily bloated. + +**Documentation Requirements** +- Doc1: Documentation should be saved in PDF format using Chrome, not any other browser, and should be PDF-friendly (no expandable panels, embedded videos, or animated GIFs). +- Doc2: The Developer Guide and User Guide should be well-structured and easily navigable in PDF format. A new user should be able to quickly locate relevant information for using the product. + +**Development Process Requirements** +- DP1: The software should be developed in a breadth-first incremental manner over the project duration. +- DP2: The project is expected to adhere to the milestone deadlines set for every week. + +**Reliability and Stability Requirements** +- R1: The application should not crash under normal operations and should handle errors gracefully without data loss. +- R2: The application should maintain a stable performance over extended usage periods. + +**Maintainability Requirements** +- M1: The software should primarily follow the Object-Oriented programming paradigm. Having a modular structure allows for the addition of new features with minimal disruption to existing functionality. -*{More to be added}* +**Quality Requirements** +- Q1: The software should be usable by a novice who has never used it before. ### Glossary * **Mainstream OS**: Windows, Linux, Unix, MacOS -* **Private contact detail**: A contact detail that is not meant to be shared with others +* **Contact**: Contact details of an entry which includes minimally a name. Phone number, address, email address and tags are optional. +* **Tag**: An custom-made field that can be associated to contacts for ease of grouping/filtering +* **Vendor**: Businesses or persons who offer wedding services, like florists, musicians, venue in-charge, etc. +* **User**: The wedding planner who is using WedLinker -------------------------------------------------------------------------------------------------------------------- @@ -588,16 +901,16 @@ testers are expected to do more *exploratory* testing. 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. + 2. Double-click the jar file Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum. -1. Saving window preferences +2. Saving window preferences 1. Resize the window to an optimum size. Move the window to a different location. Close the window. - 1. Re-launch the app by double-clicking the jar file.
+ 2. Re-launch the app by double-clicking the jar file.
Expected: The most recent window size and location is retained. -1. _{ more test cases …​ }_ +3. _{ more test cases …​ }_ ### Deleting a person @@ -605,16 +918,16 @@ testers are expected to do more *exploratory* testing. 1. Prerequisites: List all persons using the `list` command. Multiple persons in the list. - 1. Test case: `delete 1`
+ 2. Test case: `delete 1`
Expected: First contact is deleted from the list. Details of the deleted contact shown in the status message. Timestamp in the status bar is updated. - 1. Test case: `delete 0`
+ 3. Test case: `delete 0`
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)
+ 4. Other incorrect delete commands to try: `delete`, `delete x`, `...` (where x is larger than the list size)
Expected: Similar to previous. -1. _{ more test cases …​ }_ +2. _{ more test cases …​ }_ ### Saving data @@ -622,4 +935,4 @@ testers are expected to do more *exploratory* testing. 1. _{explain how to simulate a missing/corrupted file, and the expected behavior}_ -1. _{ more test cases …​ }_ +2. _{ more test cases …​ }_