diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 01f7789004d..40a8620ffe8 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -25,51 +25,51 @@ You can click on any of the links below to navigate to the respective sections f ## Table of Contents -- [1 Quick Start](#1-quick-start) - - [1.1 Prerequisites](#11-prerequisites) - - [1.1.1 Java](#111-java) - - [1.1.2 Glossary](#112-glossary) - - [1.2 Installation](#12-installation) - - [1.3 Utilisation](#13-utilisation) - - [1.4 Navigating the User Interface](#14-navigating-the-user-interface) -- [2 Features](#2-features) - - [2.1 Basic applicant management](#21-basic-applicant-management) - - [2.1.1 Adding an applicant: `add`](#211-adding-an-applicant-add) - - [2.1.2 Editing all applicants: `edit`](#212-editing-an-applicant-edit) - - [2.1.3 Deleting an applicant: `delete`](#213-deleting-an-applicant-delete) - - [2.1.4 Listing all applicants: `list`](#214-listing-all-applicant-list) - - [2.1.5 Viewing an applicant: `view`](#215-viewing-the-details-of-a-single-applicant-view) - - [2.1.6 Hiding/unhiding an applicant: `hide/unhide`](#216-hiding-an-applicant-from-list-hideunhide) - - [2.2 Applicant evaluation & comparison](#22-applicant-evaluation--comparison) - - [2.2.1 Sorting applicants by gpa: `sort-gpa`](#221-sorting-applicants-by-gpa-sort-gpa) - - [2.2.2 Sorting applicants by grades: `sort-grade`](#222-sorting-by-module-grade-sort-grade) - - [2.2.3 Sorting applicants by interview score: `sort-interview`](#223-sorting-by-interview-score-sort-interview) - - [2.2.4 Comparing 2 applicants: `compare`](#224-comparing-2-applicants-compare) - - [2.2.5 Bookmarking/Unbookmarking applicants: `bookmark/unbookmark`](#225-bookmarkingunbookmarking-applicants-bookmarkunbookmark) - - [2.2.6 Commenting on TA applicant: `comment`](#226-commenting-on-ta-applicant-comment) - - [2.3 Files and data management](#23-files-and-data-management) - - [2.3.1 Importing applicants from spreadsheet: `import`](#231-importing-applicants-from-spreadsheet-import) - - [2.3.2 Attaching file to applicant profiles: `attach`](#232-attaching-file-to-applicant-profiles-attach) -- [3 Data management](#3-data-management) - - [3.1 Saving the data](#31-saving-the-data) - - [3.2 Editing the data file](#32-editing-the-data-file) -- [4 Upcoming Features](#4-upcoming-features-coming-in-a-future-update) -- [5 FAQ](#5-faq) -- [6 Known Issues](#6-known-issues) -- [7 Summary](#7-summary) - - [7.1 Prefix Summary](#71-prefix-summary) - - [7.2 Command Summary](#72-command-summary) - - [7.2.1 Basic applicant management commands](#721-basic-applicant-management-commands) - - [7.2.2 Applicant comparison and evaluation commands](#722-applicant-comparison-and-evaluation-commands) - - [7.2.3 Data management and export commands](#723-data-management-and-export-commands) +- [1. Quick Start](#1-quick-start) + - [1.1. Prerequisites](#1-1-prerequisites) + - [1.1.1. Java](#1-1-1-java) + - [1.1.2. Glossary](#1-1-2-glossary) + - [1.2. Installation](#1-2-installation) + - [1.3. Utilisation](#1-3-utilisation) + - [1.4. Navigating the User Interface](#1-4-navigating-the-user-interface) +- [2. Features](#2-features) + - [2.1. Basic applicant management](#2-1-basic-applicant-management) + - [2.1.1. Adding an applicant: `add`](#2-1-1-adding-an-applicant-add) + - [2.1.2. Editing all applicants: `edit`](#2-1-2-editing-an-applicant-edit) + - [2.1.3. Deleting an applicant: `delete`](#2-1-3-deleting-an-applicant-delete) + - [2.1.4. Listing all applicants: `list`](#2-1-4-listing-all-applicant-list) + - [2.1.5. Viewing an applicant: `view`](#2-1-5-viewing-the-details-of-a-single-applicant-view) + - [2.1.6. Hiding/unhiding an applicant: `hide/unhide`](#2-1-6-hiding-an-applicant-from-list-hide-unhide) + - [2.2. Applicant evaluation & comparison](#2-2-applicant-evaluation-and-amp-comparison) + - [2.2.1. Sorting applicants by gpa: `sort-gpa`](#2-2-1-sorting-applicants-by-gpa-sort-gpa) + - [2.2.2. Sorting applicants by grades: `sort-grade`](#2-2-2-sorting-by-module-grade-sort-grade) + - [2.2.3. Sorting applicants by interview score: `sort-interview`](#2-2-3-sorting-by-interview-score-sort-interview) + - [2.2.4. Comparing 2 applicants: `compare`](#2-2-4-comparing-2-applicants-compare) + - [2.2.5. Bookmarking/Unbookmarking applicants: `bookmark/unbookmark`](#2-2-5-bookmarkingunbookmarking-applicants-bookmarkunbookmark) + - [2.2.6. Commenting on TA applicant: `comment`](#2-2-6-commenting-on-ta-applicant-comment) + - [2.3. Files and data management](#2-3-files-and-data-management) + - [2.3.1. Importing applicants from spreadsheet: `import`](#2-3-1-importing-applicants-from-spreadsheet-import) + - [2.3.2. Attaching file to applicant profiles: `attach`](#2-3-2-attaching-file-to-applicant-profiles-attach) +- [3. Data management](#3-data-management) + - [3.1. Saving the data](#3-1-saving-the-data) + - [3.2. Editing the data file](#3-2-editing-the-data-file) +- [4. Upcoming Features](#4-upcoming-features-coming-in-a-future-update) +- [5. FAQ](#5-faq) +- [6. Known Issues](#6-known-issues) +- [7. Summary](#7-summary) + - [7.1. Prefix Summary](#7-1-prefix-summary) + - [7.2. Command Summary](#7-2-command-summary) + - [7.2.1. Basic applicant management commands](#7-2-1-basic-applicant-management-commands) + - [7.2.2. Applicant comparison and evaluation commands](#7-2-2-applicant-comparison-and-evaluation-commands) + - [7.2.3. Data management and export commands](#7-2-3-data-management-and-export-commands) -------------------------------------------------------------------------------------------------------------------- -## 1 Quick start +## 1. Quick start -### 1.1 Prerequisites +### 1.1. Prerequisites -#### 1.1.1 Java +#### 1.1.1. Java Ensure you have [Java `11`](https://www.oracle.com/sg/java/technologies/javase/jdk11-archive-downloads.html) or above installed. Java is the language that your computer uses to understand TAfinder. @@ -94,7 +94,7 @@ An example is shown below.
-#### 1.1.2 Glossary +#### 1.1.2. Glossary | Words/Abbreviations | Explanation | |---------------------|-------------------------------------------------------------------------------------------------------------------------------------| | **TA** | Teaching Assistant | @@ -105,7 +105,7 @@ An example is shown below. | **Toast** | A popup alert to inform users about certain information | | **Tag** | Tags are associated with applicants, users can tag applicants with any keyword they want,
the number of tags are not restricted | -### 1.2 Installation +### 1.2. Installation **Step 1.** Download the latest `tafinder.jar` from [here](). @@ -135,7 +135,7 @@ An example of the final command is displayed below. The GUI similar to the below should appear in a few seconds. ![Ui](images/Ui.png) -### 1.3 Utilisation +### 1.3. Utilisation **Step 1:** Type the command in the Command Input Box and press Enter to execute it. e.g. typing **`help`** and pressing Enter will open the help window.
@@ -163,7 +163,7 @@ OR return to the [Table of Contents](#table-of-contents) to find your desired co -### 1.4 Navigating the User Interface +### 1.4. Navigating the User Interface ![UI with shaded areas](images/tafinder-UI.png) The UI has the following areas: @@ -179,7 +179,7 @@ The UI has the following areas: -------------------------------------------------------------------------------------------------------------------- -## 2 Features +## 2. Features @@ -216,95 +216,103 @@ lines as space characters surrounding line-breaks may be omitted when copied ove --- -### **2.1 Basic applicant management** +### 2.1. Basic applicant management -#### 2.1.1 Adding an applicant: `add` +#### 2.1.1. Adding an applicant: `add` -![add.jpg](images/add.jpg) - - - -Adds a new applicant to the list of applicants. - - - - +You have just finished setting up TAfinder and you are ready to add your first applicant. +Let's find out how you can add the applicant to the list. **Format:** -**`add [s/STUDENT_NUMBER] [n/NAME] [p/PHONE] [e/EMAIL] [g/GPA] [c/comment] [t/TAG]…`** +**`add s/STUDENT_NUMBER n/NAME p/PHONE e/EMAIL g/GPA [pg/PREVIOUS_GRADE] [is/INTERVIEW_SCORE] [c/COMMENT] [t/TAG]…`** - + - **`s/STUDENT_NUMBER`**: Student number of the applicant - **`n/NAME`**: Name of the applicant. - **`p/PHONE`**: Phone number of the applicant. - **`e/EMAIL`**: Email address of the applicant. - **`g/GPA`**: GPA of the applicant. -- **`c/COMMENT`**: Comments for the applicant. -- **`t/TAG`**: Tags of the applicant. Note that editing tags will replace existing tags; it is not cumulative. +- **`pg/PREVIOUS_GRADE`**: Previous grade of the applicant. +- **`[is/INTERVIEW_SCORE]`**: Interview score of the applicant. +- **`[c/COMMENT]`**: Comments for the applicant. +- **`[t/TAG]`**: Tags of the applicant. + + +You can add more than 1 tag to an applicant by adding more `t/TAG` parameters. + - +Here are some examples you can try with the `add` command. **Examples:** - + -**`add s/A0269357C n/john doe p/91234567 e/johndoe@example.com g/5.0 c/ t/pastTA t/deanslist`** -- Adds a person with the following information: - - **Student number**: A0269357C - - **Name**: John Doe - - **Phone number**: 91234567 - - **Email address**: johndoe@example.com - - **GPA**: 5.0 - - **Comment**: - - - **Tags**: pastTA, deanslist +**`add s/A0251647W n/amanda p/89064678 e/amanda@example.com g/4.3 pg/A`** +- Adds an applicant with the following information: + - **Student number**: A0251647W + - **Name**: Amanda + - **Phone number**: 89064678 + - **Email address**: amanda@example.com + - **GPA**: 4.3 + - **Previous grade**: A - + -**`add s/A0251647W n/amanda p/89064678 e/amanda@example.com g/4.3 c/Hardworking`** -- Adds a person with the following information: - - **Student number**: A0251647W - - **Name**: Amanda - - **Phone number**: 89064678 - - **Email address**: amanda@example.com - - **GPA**: 4.3 - - **Comment**: Hardworking +**`add s/A0269357C n/john doe p/91234567 e/johndoe@example.com g/5.0 pg/A- is/8.9 c/Hardworking t/pastTA t/deanslist`** +- Adds an applicant with the following information: + - **Student number**: A0269357C + - **Name**: John Doe + - **Phone number**: 91234567 + - **Email address**: johndoe@example.com + - **GPA**: 5.0 + - **Previous grade**: A- + - **Interview score**: 8.9 + - **Comment**: Hardworking + - **Tags**: pastTA, deanslist - +Following the example above, if you entered everything correctly, you should see the following: - +![add.jpg](images/add_command_image_UG.png) + +You have now successfully added your first applicant to the list. As you add more applicants to the list, +watch out for the expected and erroneous messages below that could be displayed in the command result screen! + + **Expected Outputs:** -Successfully adding applicant and applicant's information.
-Confirmation message:
-**`"New applicant added: Student number: ; Name: ; Phone: ; Email: ; GPA: ; Comment: ; Tags: "`** +Successfully added applicant and his/her information:
+**`"New applicant added: Student number: ; Name: ; Phone: ; +Email: ; GPA: ; Previous grade: ; [Interview score: ]; +[Comment: ]; [Tags: ]."`** - + -**Errors:** +**Erroneous Outputs:** Invalid command format:
**`"Invalid command format!"`
-`"add: Adds an applicant to the list. Parameters: s/STUDENT NUMBER n/NAME p/PHONE e/EMAIL g/GPA c/comment [t/TAG]..."`
-`"Example: add s/A0343434C n/John Doe p/98765432 e/johnd@example.com g/4.9 c/Hardworking and diligent t/pastTA"`** +`"add: Adds an applicant to the list. Parameters: s/STUDENT NUMBER n/NAME p/PHONE e/EMAIL g/GPA pg/PREV GRADE +[is/INTERVIEW SCORE] [c/COMMENT] [t/TAG]..."`
+`"Example: add s/A0343434C n/John Doe p/98765432 e/johnd@example.com g/4.9 pg/A is/9.1 c/Hardworking and diligent t/pastTA "`** @@ -315,18 +323,11 @@ Repeated applicant:
 - - -Missing fields:
-**`"Error: Missing fields. Please follow the format: add [n/NAME] [p/PHONE] [e/EMAIL] [g/GPA] [t/TAG]…"`** - - - --- -#### 2.1.2 Editing an applicant: `edit` +#### 2.1.2. Editing an applicant: `edit` ![edit function UI](images/editUI.png) @@ -426,7 +427,7 @@ Index out of range:
--- -#### 2.1.3 Deleting an applicant: `delete` +#### 2.1.3. Deleting an applicant: `delete` ![delete function UI](images/delete-UI.png) @@ -501,7 +502,7 @@ Index out of range:
--- -#### 2.1.4 Listing all applicant: `list` +#### 2.1.4. Listing all applicant: `list` ![listUI-1](images/listUI-1.png) ![listUI-2](images/listUI-2.png) @@ -542,7 +543,7 @@ Shows a list of all applicants. --- -#### 2.1.5 Viewing the details of a single applicant: `view` +#### 2.1.5. Viewing the details of a single applicant: `view` ![edit function UI](images/viewUI.png) @@ -637,7 +638,7 @@ Index out of range:
 --- -#### 2.1.6 Hiding an applicant from list: `hide`/`unhide` +#### 2.1.6. Hiding an applicant from list: `hide`/`unhide` ![hide function UI](images/hideUI.png) @@ -742,9 +743,9 @@ Index out of range:
--- -### **2.2 Applicant evaluation & comparison** +### 2.2. Applicant evaluation & comparison -#### 2.2.1 Sorting applicants by GPA: `sort-gpa` +#### 2.2.1. Sorting applicants by GPA: `sort-gpa` ![sort function UI](images/sortUI.png) @@ -789,15 +790,15 @@ Empty list:
--- -#### 2.2.2 Sorting by module grade: `sort-grade` +#### 2.2.2. Sorting by module grade: `sort-grade` --- -#### 2.2.3 Sorting by interview score: `sort-interview` +#### 2.2.3. Sorting by interview score: `sort-interview` --- -#### 2.2.4 Comparing 2 applicants: `compare` +#### 2.2.4. Comparing 2 applicants: `compare` ![compare function UI](images/compareUI.png) @@ -884,7 +885,7 @@ Comparing the same applicant:
--- -#### 2.2.5 Bookmarking/Unbookmarking applicants: `bookmark/unbookmark` +#### 2.2.5. Bookmarking/Unbookmarking applicants: `bookmark/unbookmark` ![bookmark function UI](images/bookmarkUI.png) @@ -967,7 +968,7 @@ Index out of range:
--- -#### 2.2.6 Commenting on TA applicant: **`comment`** +#### 2.2.6. Commenting on TA applicant: **`comment`** ![comments.jpg](images/comment.jpg) @@ -1046,9 +1047,9 @@ Index out of range:
--- -### 2.3 Files and data management +### 2.3. Files and data management -#### 2.3.1 Importing applicants from spreadsheet: `import` +#### 2.3.1. Importing applicants from spreadsheet: `import` @@ -1112,7 +1113,7 @@ Missing file permissions or invalid file path:
--- -#### 2.3.2 Attaching file to applicant profiles: `attach` +#### 2.3.2. Attaching file to applicant profiles: `attach` ![attach function UI](images/attachUI.png) @@ -1197,12 +1198,12 @@ Any other unexpected error:
 --- -## 3 Data Management -### 3.1 Saving the data +## 3. Data Management +### 3.1. Saving the data TAfinder data are saved in the hard disk automatically after any command that changes the data. There is no need to save manually. -### 3.2 Editing the data file +### 3.2. Editing the data file TAfinder data are saved automatically as a JSON file `[JAR file location]/data/tafinder.json`. Advanced users are welcome to update data directly by editing that data file. @@ -1215,24 +1216,24 @@ If your changes to the data file makes its format invalid, TAfinder will discard -------------------------------------------------------------------------------------------------------------------- -## 4 Upcoming Features [coming in a future update!] +## 4. Upcoming Features [coming in a future update!] -------------------------------------------------------------------------------------------------------------------- -## 5 FAQ +## 5. FAQ **Q**: How do I transfer my data to another Computer?
**A**: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous AddressBook home folder. -------------------------------------------------------------------------------------------------------------------- -## 6 Known Issues +## 6. 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. -------------------------------------------------------------------------------------------------------------------- -## 7 Summary -### 7.1 Prefix Summary +## 7. Summary +### 7.1. Prefix Summary | Parameter | Prefix | Rules | |----------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Student number | s/ | - Should be in the format `AdddddddL`,
where `d` represents digit and `L` represents capital letters. | @@ -1244,8 +1245,8 @@ If your changes to the data file makes its format invalid, TAfinder will discard | Tag | t/ | - Should only contain alphanumeric characters.
- Should not contain spaces. | -### 7.2 Command Summary -#### 7.2.1 Basic applicant management commands +### 7.2. Command Summary +#### 7.2.1. Basic applicant management commands | Action | Format, Examples | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Add** | - `add [s/STUDENT_NUMBER] [n/NAME] [p/PHONE] [e/EMAIL] [g/GPA] [t/TAG]…`
- e.g., `add s/A0269357C n/john doe p/91234567 e/johndoe@example.com g/5.0 t/pastTA t/deanslist` | @@ -1255,7 +1256,7 @@ If your changes to the data file makes its format invalid, TAfinder will discard | **View** | - `view INDEX`
- e.g., `view 3` | | **Hide/Unhide** | - `hide INDEX` / `unhide INDEX`
- e.g., `hide 3` / `unhide 3` | | -#### 7.2.2 Applicant comparison and evaluation commands +#### 7.2.2. Applicant comparison and evaluation commands | Action | Format, Examples | |-------------------------|-----------------------------------------------------------------------------------| | **Sort GPA** | - `sort-gpa` | @@ -1264,7 +1265,7 @@ If your changes to the data file makes its format invalid, TAfinder will discard | **Comment** | - `comment INDEX COMMENT`
- e.g., `comment 3 Hardworking` | -#### 7.2.3 Data management and export commands +#### 7.2.3. Data management and export commands | Action | Format, Examples | |-------------------------|-----------------------------------------------------------------| | **Export** | - `export FILENAME`
- e.g., `export ta-applicants.csv` | diff --git a/docs/images/add_command_image_UG.png b/docs/images/add_command_image_UG.png new file mode 100644 index 00000000000..f8d0760df34 Binary files /dev/null and b/docs/images/add_command_image_UG.png differ