diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 6c5e50b022b..05d864ebcee 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -18,6 +18,8 @@ This guide will equip you with everything you need to maximize the benefits of C **Unique ID System:** Each contact in ContactSwift is assigned a unique identifier (UID), ensuring precise and efficient management of contact details. This UID is key to performing actions like editing, deleting, or adding tasks for specific contacts. You will encounter these UIDs as you use various commands, offering a streamlined way to manage large datasets. This system is designed to enhance the user experience, enabling you to easily deal with duplicates! + +Data modifications may cause unexpected errors. It is recommended to back up the data file before making any changes. Please refer to the [Saving the Data](#saving-the-data) section for more information. **Who is this for?** This guide is tailored for small business owners and remote team managers seeking an effective solution to manage contact details and tasks. We assume users have a basic understanding of command-line operations but have structured this guide to be accessible even to those new to CLI environments. @@ -45,7 +47,11 @@ Check the [Glossary](#glossary) for explanations of technical terms to ensure a 4. [FAQ](#faq) 5. [Known Issues](#known-issues) 6. [Command Summary](#command-summary) -7. [Glossary](#glossary) +7. [Feedback and Support](#feedback-and-support) + - [How to Provide Feedback](#how-to-provide-feedback) + - [Feedback Etiquette](#feedback-etiquette) + - [What Happens to Your Feedback](#what-happens-to-your-feedback) +8. [Glossary](#glossary) --- @@ -58,8 +64,8 @@ Embark on your ContactSwift journey with these straightforward steps: 3. **Setup**: Select a folder as your home for ContactSwift and move the downloaded file there. 4. **Launch**: Open a command terminal, navigate to your home folder, and initiate the application with `java -jar contactswift.jar`. The GUI, populated with sample data, will appear as shown below: - ![ContactSwift Main Interface](./images/v1.3.png) - _Figure 1: The main interface of ContactSwift, showcasing sample data._ +![ContactSwift Main Interface](./images/v1.3.png) +_Figure 1: The main interface of ContactSwift, showcasing sample data._ 5. **Get Commanding**: Input commands in the command box and press Enter. Try these to get started: - `list` – Displays all contacts. @@ -74,6 +80,8 @@ Embark on your ContactSwift journey with these straightforward steps: For a detailed explanation of all commands, refer to the [Features](#features) section. +[Back to table of contents](#table-of-contents) + --- ## Features @@ -100,6 +108,8 @@ For a detailed explanation of all commands, refer to the [Features](#features) s - If you are using a PDF version of this document, be careful when copying and pasting commands that span multiple lines as space characters surrounding line-breaks may be omitted when copied over to the application. +[Back to table of contents](#table-of-contents) + ### Viewing help : `help` Shows a message explaining how to access the help page. @@ -129,6 +139,8 @@ Examples: **Caution:** Ensure the `PHONE_NUMBER` is valid; ContactSwift does not accept phone numbers with less than 3 digits. +[Back to table of contents](#table-of-contents) + ### Locating employees by name: `find` Finds employees whose names contain any of the given keywords. @@ -151,6 +163,7 @@ Examples: Before using any task-related commands (`addTask`, `mark`, `unmark`, `deleteTask`), you must first find the employee using the `find` command. This ensures that the employee's information is correctly loaded and visible in the [UI (User Interface)](#ui-user-interface), and any subsequent commands will reflect their effects immediately in the UI. Example of using the `find` command: + - `find John Doe` will search and display the tasks and details of 'John Doe' in the UI. **Caution:** Due to a current bug, if you do not use the `find` command to locate and display the employee's details before executing other commands, the changes may not immediately reflect in the UI. @@ -167,9 +180,12 @@ Format: `addTask uid/UID DESCRIPTION` - The description of the task can only contain alphanumeric characters and spaces, and cannot be empty. Examples: + - `addTask uid/1 Complete the report by 5pm` - `addTask uid/2 Submit the proposal by 10am` +[Back to table of contents](#table-of-contents) + ### Mark a task as completed: `mark` Marks a task as completed in the employee's task list. @@ -184,9 +200,12 @@ Format: `mark uid/UID TASKINDEX` **Caution:** This command can mark a task that is already marked as completed. Use this feature carefully to avoid misrepresenting the completion status of tasks. Examples: + - `mark uid/1 2` marks the 2nd task in the task list of the employee with the `UID` of 1 as completed. - `mark uid/2 1` marks the 1st task in the task list of the employee with the `UID` of 2 as completed. +[Back to table of contents](#table-of-contents) + ### Unmark a task as completed: `unmark` Unmarks a task as completed in the employee's task list. @@ -201,9 +220,12 @@ Format: `unmark uid/UID TASKINDEX` **Caution:** This command can unmark a task that is not marked as completed. Be cautious to ensure accurate tracking of task completion status. Examples: + - `unmark uid/1 2` unmarks the 2nd task in the task list of the employee with the `UID` of 1 as not completed. - `unmark uid/2 1` unmarks the 1st task in the task list of the employee with the `UID` of 2 as not completed. +[Back to table of contents](#table-of-contents) + ### Delete a task from an employee's task list: `deleteTask` Deletes a task from an employee's task list. @@ -216,9 +238,12 @@ Format: `deleteTask uid/UID TASKINDEX` - The `TASKINDEX` **must be a positive integer** 1, 2, 3, …​ and must exist as displayed in the UI. Examples: + - `deleteTask uid/1 2` deletes the 2nd task in the task list of the employee with the `UID` of 1. - `deleteTask uid/2 1` deletes the 1st task in the task list of the employee with the `UID` of 2. +[Back to table of contents](#table-of-contents) + ### Filter employees by name, tags, roles, or teams: `filter` The `filter` command is used to search for employees based on specific attributes such as their name, tags, roles, or teams. This powerful tool allows you to narrow down the list of employees to those who meet certain criteria, making it easier to manage and interact with your employees. @@ -248,6 +273,8 @@ Examples: - `filter t/remote` should produce a similar output as below:
![result for 'filter tag remote'](./images/filterTagRemoteResult.png) +[Back to table of contents](#table-of-contents) + ### Listing all employees : `list` Shows a list of all employees in the address book. @@ -271,6 +298,7 @@ Examples: - `edit 1 p/91234567 e/johndoe@example.com` Edits the phone number and email address of the 1st employee to be `91234567` and `johndoe@example.com` respectively. - `edit 2 n/Betsy Crower t/` Edits the name of the 2nd employee to be `Betsy Crower` and clears all existing tags. +[Back to table of contents](#table-of-contents) ### Deleting an employee : `delete` @@ -293,6 +321,8 @@ Examples: - `delete betsy` deletes the employee with the name `betsy` if there are no duplicates. In the case of duplicates, the user will be prompted to delete by uid. - `delete uid/101` deletes the employee with the `uid` of 101. +[Back to table of contents](#table-of-contents) + ### Clearing all entries : `clear` Clears all entries from the address book. @@ -305,6 +335,8 @@ Exits the program. Format: `exit` +[Back to table of contents](#table-of-contents) + ### Saving the Data ContactSwift data are saved in the hard disk automatically after any command that changes the data. There is no need to save manually. @@ -312,9 +344,11 @@ ContactSwift data are saved in the hard disk automatically after any command tha **Note:** While ContactSwift attempts to save automatically, it's good practice to regularly back up your data file, especially before making bulk changes or updates. -**Caution:** If your changes to the data file make its format invalid, ContactSwift will discard all data and start with an empty data file at the next run. We recommend taking a backup of the file before editing it. Furthermore, certain edits can cause ContactSwift to behave in unexpected ways (e.g., if a value entered is outside the acceptable range). Edit the data file only if you are confident that you can update it correctly. +**Caution:** If your changes to the data file make its format invalid, ContactSwift will discard all data and start with an empty data file or template data at the next run. We recommend taking a backup of the file before editing it. Furthermore, certain edits can cause ContactSwift to behave in unexpected ways (e.g., if a value entered is outside the acceptable range). Edit the data file only if you are confident that you can update it correctly. +[Back to table of contents](#table-of-contents) + --- # Managing your employees @@ -335,6 +369,8 @@ Within the dynamic interface of ContactSwift, each employee now boasts a visible We believe that the Completion Rate Statistics feature will significantly contribute to enhancing the efficiency and productivity of your team, offering a clear, quantifiable measure of task management success. We are confident that this addition will empower you and your team to achieve and surpass your productivity goals. +[Back to table of contents](#table-of-contents) + ### Archiving data files `[coming in v2.0]` _Details coming soon ..._ @@ -349,18 +385,46 @@ _Details coming soon ..._ **Q2: How can I transfer my ContactSwift data to another computer?** **A2:** Install ContactSwift on the other computer and overwrite the empty data file it creates with the file that contains the data of your previous ContactSwift home folder. +**Q3: How do I change the data file that ContactSwift uses?** +**A3:** ContactSwift uses the file `data/addressbook.json` in the home folder by default. You can modify the data inside that file or replace it with another file of the same name. + +**Q4: If I modify the data how do I know it won't run into errors?** +**A4:** ContactSwift can run into unexpected errors if the data file is modified incorrectly. It is recommended to back up the data file before making any changes. However, the command line will log an error message if the data file is corrupted and provide feedback on what went wrong. Depending on the error, the software may start with an empty data file or a template file. + +**Q5: What happens if I run commands with corrupted data ?** +**A5:** ContactSwift will overwrite the corrupted data file with a new one and start with an empty address book. + +**Q6: How can I print the contact details or task list?** +**A6:** Currently, ContactSwift does not support direct printing. However, you can the JSON file to some other format (like CSV) and print it. + +**Q7: What are the limits on the number of contacts or tasks I can add?** +**A7:** ContactSwift does not have a hard limit on the number of contacts or tasks you can add. However, the performance may degrade with a large number of contacts or tasks. For all practical purposes however the application should be able to handle a few thousand contacts and tasks. + +**Q9: Can I customize the fields for each contact or task in ContactSwift?** +**A9:** ContactSwift does not support custom fields for contacts or tasks. However, you can use the tags field to add additional information. + +**Q10: How do I report a bug or issue with ContactSwift?** +**A10:** Please refer to the [Feedback and Support](#feedback) section for information on how to report bugs or issues. + +**Q11: How do I request a new feature for ContactSwift?** +**A11:** Please refer to the [Feedback and Support](#feedback) section for information on how to request new features. + +[Back to table of contents](#table-of-contents) + --- ## Known issues 1. **When using multiple screens**, if you move the application to a secondary screen, and later switch to using only the primary screen, the GUI will open off-screen. The remedy is to delete the `preferences.json` file created by the application before running the application again. +[Back to table of contents](#table-of-contents) + --- ## Command summary | Action | Format, Examples | -|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Add** | `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS T/TEAM r/ROLE [t/TAG]…​`
e.g., `add n/James Ho p/22224444 e/jamesho@example.com a/123, Clementi Rd, 1234665 T/A r/Cleaner t/friend t/colleague` | | **Add Task** | `addTask uid/UID DESCRIPTION`
e.g., `addTask uid/1 Complete the report by 5pm`, `addTask uid/2 Submit the proposal by 10am` | | **Clear** | `clear` | @@ -375,8 +439,50 @@ _Details coming soon ..._ | **Mark Task** | `mark uid/UID TASKINDEX`
e.g., `mark uid/1 3` | | **Unmark Task** | `unmark uid/UID TASKINDEX`
e.g., `unmark uid/1 2` | +[Back to table of contents](#table-of-contents) + --- +## Feedback and Support + +Feedback is a crucial component of continuous improvement for ContactSwift. We actively encourage users, developers, and stakeholders to provide feedback to help us enhance both the functionality of ContactSwift and the usefulness of this Developer Guide. + +Here are the ways you can contribute feedback and suggestions: + +### How to Provide Feedback + +#### Issue Tracker + +For technical issues, bugs, or feature requests, please use our [official Issue Tracker](https://github.com/AY2324S2-CS2103T-T17-2/tp/issues). This allows us to categorize and prioritize issues effectively. When submitting an issue, please include as much detail as possible, such as the steps to reproduce the issue, expected versus actual behavior, and environment details (OS, ContactSwift version, etc.). + +#### Email + +If you have suggestions for improving the Developer Guide or need to discuss matters that require discretion, we'll be providing our email soon here. We appreciate detailed feedback that includes specific sections or topics and any recommendations for improvement. + +#### Surveys and Feedback Forms + +Periodically, we may circulate surveys or feedback forms to gather comprehensive opinions on specific aspects of ContactSwift or the Developer Guide. These are excellent opportunities to influence the future direction of the software and documentation. + +### Feedback Etiquette + +Constructiveness: We highly value constructive feedback that provides actionable insights and suggestions for improvement. + +Respect and Courtesy: Engage respectfully and professionally with community members and maintain a supportive environment. + +Confidentiality: Avoid sharing sensitive or confidential information in public forums or issue trackers. + +### What Happens to Your Feedback + +1. Review Process: All feedback is reviewed by the development team. We prioritize actions based on the impact, feasibility, and alignment with our development roadmap. + +2. Implementation: If your feedback leads to a change or improvement, we will acknowledge contributions in upcoming release notes or directly within the revised sections of the guide. + +3. Response: While we aim to respond to all feedback, the volume of input may affect our ability to reply individually. However, we value every piece of feedback and strive to incorporate it as best as we can. + +Your insights and contributions are invaluable to us and help ensure that ContactSwift continues to evolve in ways that meet and exceed user needs and expectations. Thank you for helping us improve and for being an active member of our community. + +[Back to table of contents](#table-of-contents) + ## Glossary ### CLI (Command Line Interface) @@ -399,4 +505,6 @@ UID is a unique identifier assigned to each contact in ContactSwift, enabling pr Any combination of the alphabets A-Z and numbers 0-9. +[Back to table of contents](#table-of-contents) + ---