diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index aa01813aac6..9fe6e56f0f1 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -499,7 +499,6 @@ Cons: It restricts users from entering data that might be understandable or conv * wants an organized way to keep track of candidates information * wants to view and manage candidates information in a single place * wants to filter and sort candidates based on their details -* wants to compare candidates using their information * wants to view a schedule/summary of events relating to the candidates * wants to attach a score to candidate performance over interview and assessments * wants to be able to use scores in order to quantitatively compare candidates @@ -858,9 +857,39 @@ This makes it more intuitive and logical for the user to use since the user woul **Improve the search and filter feature** Currently, the UI does not update and will remain unchanged from the previous command. This may be confusing or inaccurate and thus it should remain blank +### Improve on `remark` feature +**Improve the remark feature** +Currently, if you use multiple prefix , it is allowed and only the last prefix will be used. We would like to improve on this by only allowing 1 prefix to be used. Thus we verify for duplicate `r/` prefix since it does not make sense to have multiple remarks for the same person. + ## **Appendix: Effort** -### Based on over-arching features +### ScoreList, Score, Summary Statistic, Filter +In terms of integration of features, this was by far the biggest and most complex. This is due to how `Summary Statistic` relied on `Score`, `ScoreList` and `Tag` to function and Filter requiring all of them to function properly. +The thought process came when we first tried to implement 1 score for each applicant. This was the naive approach. However, we realise that with only 1 score, would mean that it can only represent 1 thing. +This means that the Hiring Manager would have to keep track of what each score means individually and any point in arranging these scores would lead to massive confusion. Hence, we decided to attach a score to a tag. +However, this meant that with optional and possibly multiple tagging, we will need a flexible way of attaching scores to tags. This led to the HashMap implementation of `ScoreList`. +Additionally, we had to decide on the constraint of scores. While a common approach was to let it be between 0 and 100, we wanted to maintain great flexibility and thus constraint it as a positive integer >= 0. + +For storage wise, we had to learn how to store `ScoreList` in a key-value format and also decode it. So that was one big challenge in terms of storing it in a json format that can be decoded. + +One of the biggest problem with using the `Parser` and `Command` model is that the `Parser` has no access to the model. So at the parsing stage, you are unable to determine if the tag exists or is valid since we only want to enable it for `assessment` tags. +This meant that it had to be carried out at the `Command` stage of execution. Additionally, it might have been a misstep trying to implement the editing of scores in the `edit` command. +This is due to the complexity of how the `edit` command was implemented. Since you could add a tag in edit while simultaneously trying to add a score to the tag, it led to a lot of need to check. +Additionally since tags can be easily edited, it meant that we needed to check if the ScoreList was updated and if the tag was edited. +This also led to many errors, since you could remove all tags, and the ScoreList would still remain. Especially since EditPersonDescriptor did not have access to the tags that the person currently have. +Additionally, since tag was not cumulative, you would want to keep track of the scores of the current tag if they are being kept. This meant that you would need to keep track of the current tag and the current score while also allowing for changes. + +After that, there was the choice of implementing Summary Statistic. A lot of thought went into how we can make the scores useful. What would be a great visualisation. We chose the couple of simple statistic that we thought would be useful. +However, the calculation of the statistic was not simple since we decided to use streams for implementation. This meant that misconception of how streams work would lead to a lot of errors. The most common 1 being that the stream is closed due to a close operation. +Additionally, percentile was originally implemented incorrectly. This was because we did not account for the edge case of people scoring the same. This meant that the percentile would vary for same score. This was fixed by then subtracting the number of people with the same score from the total number of people. + + +Following that we had filter which relied on all of the above. This was simpler to implement once all the logic was down. +Overall, the implementation of the feature was complex due to nature of Streams and UI updates for JavaFX. + +### View +UI generation was rather tedious in terms of using CSS and trying to get things to align properly. Additionally, the design implementation using `Commands` meant that commands did not have access to other commands during runtime. +This meant that we had to add an extra parameter to the CommandResult in order to get commands to auto execute view after executing the command. The implementation was simple but the design was not. ### Flexibility for further analysis We acknowledge that there will be some who would prefer to analyse data outside JABPro - and that is completely fine. diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 25143325357..cc51c754472 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -148,7 +148,8 @@ Not to worry, here are some steps you can take to fix this: 4. You should be able to see a file titled `addressbook.json`. Run `rm addressbook.json` to delete this file. 5. Run `cd ..` to navigate back to the folder you were in before. 6. Run `java -jar jabpro.jar` to relaunch the application. You should be able to see a GUI similar to the one above. - + + 5. If your UI looks **compressed and words are being cut off such as that seen below**, you should **resize** the window to a larger size by dragging the corners of the application window. The UI should now look like the example given above.
@@ -240,7 +241,7 @@ Not to worry, here are some steps you can take to fix this: 4. The UI below will not be updated if your command has failed. -** The example below shows a command failure for `view`:** +**The example below shows a command failure for `view`:** ![CommandFailure](images/view-command-failure.png)
@@ -325,7 +326,7 @@ Format: `remark INDEX r/REMARK` **Notes regarding `remark` command:** * The previous remark is not saved, and instead is replaced by the inputted remark. The command does not add to the existing remark. * You can empty out a remark by inputting `r/` without any text after it or by omitting the `r/` prefix. -* You can get the remark previously inputted by using the **REMARK** keyword. It will be replaced with the previous remark. The keyword **REMARK** is case-sensitive. This means that `remark 1 r/**remark**` will just replace the remark with the word `**remark**`. +* You can get the remark previously inputted by using the `**REMARK**` keyword. It will be replaced with the previous remark. The keyword `**REMARK**` is case-sensitive. This means that `remark 1 r/**remark**` will just replace the remark with the word `**remark**`. * You can use multiple prefix for `remark` but only the last prefix will be used. This means that `remark 1 r/remark r/remark2` will just replace the remark with `remark2`. @@ -462,7 +463,6 @@ Format: `set INDEX STATUS` **Notes regarding `set` command:** * The index used will be the same index as the one shown in the displayed applicant list. - Sets the applicant to a specific status ("Preliminary"/ "Interviewed"/ "Rejected"/ "Offered") @@ -1105,11 +1105,11 @@ You should ensure that you have **sufficient candidates of more than 20** with a **Formula used to calculate the summary statistics:** -**mean** is calculated by using the formula `sum of all scores with that tag / number of applicants with that tag` -**median** is calculated by using the formula `middle score of all scores with that tag` -**minimum** is calculated by using the formula `lowest score of all scores with that tag` -**maximum** is calculated by using the formula `highest score of all scores with that tag` -**percentile** is calculated by using the formula `number of applicants with a score strictly lower than the applicant / total number of applicants with that tag` +**mean** is calculated by using the formula `sum of all scores with that tag / number of applicants with that tag` +**median** is calculated by using the formula `middle score of all scores with that tag` +**minimum** is calculated by using the formula `lowest score of all scores with that tag` +**maximum** is calculated by using the formula `highest score of all scores with that tag` +**percentile** is calculated by using the formula `number of applicants with a score strictly lower than the applicant / total number of applicants with that tag` ### Saving the data diff --git a/docs/team/sk2001git.md b/docs/team/sk2001git.md index 36bb2ddb353..aa69498cbd5 100644 --- a/docs/team/sk2001git.md +++ b/docs/team/sk2001git.md @@ -27,40 +27,45 @@ Thereby additional enhancement that I have implemented to support filter are: 1. Overloading the current `edit` command to edit the score of a candidate for a particular assessment. 2. Summary Statistic -For this TP project, I have mainly been in charge of the UI. This is due to extensive interaction needed for the `View` and `Summary Statistic` panels -Nonetheless, I have also contributed greatly to backend features such as `Remark`, `Edit`, `Filter`, `Summary Statistic` -This has allowed me to gain experience and understanding of the backend and frontend of the application and thus can be considered a full stack developer. - -For the team administration, I have acted as the work manager, ensuring that everyone is on track to meet the deadlines and objectives. -In terms of the UG and DG, I have been in charge of the overall structure and formatting of the UG and DG. This is to ensure that the UG and DG is consistent and easy to read for the user. - ## Summary of Contributions **Code contributed**: [RepoSense link](https://nus-cs2103-ay2324s1.github.io/tp-dashboard/?search=sk2001git&sort=groupTitle%20dsc&sortWithin=title&since=2023-09-22&timeframe=commit&mergegroup=&groupSelect=groupByRepos&breakdown=false&tabOpen=true&tabType=authorship&tabAuthor=sk2001git&tabRepo=AY2324S1-CS2103T-W09-4%2Ftp%5Bmaster%5D&authorshipIsMergeGroup=false&authorshipFileTypes=docs&authorshipIsBinaryFileTypeChecked=false&authorshipIsIgnoredFilesChecked=false) **Enhancement implemented**: * Remark command -* Edit command (for scores) +* Edit command (For scores) * Filter command * View command +* Person (ScoreList, Remark) +* Score * Summary Statistic * UI for View Panel and Summary statistic panel +* Storage saving for Score, ScoreList, Remark **Contribution to the UG**: -* Updated UG for the `add` command -* Updated UG for the `remark` command -* Updated UG for the `filter` command -* Updated UG for the `view` command -* Updated UG for the `edit` command -* Updated UG for the `Summary Statistic` section +* Updated the UG for the entire table of contents +* Updated the UG for `Overview of Main Features` for Introduction +* Updated UG for the `add`, `remark`, `filter`, `view`, `edit` command and `Summary Statistic` section **Contribution to DG**: -* Contributed to DG for writing User Stories +* Contributed to DG for writing User Stories + * 5 of the `* * *` Must-have features for user stories which links to the commands I have implemented +* Contributed to DG for target user profile + * wants an organized way to keep track of candidates information + * wants to view and manage candidates information in a single place + * wants to attach a score to candidate performance over interview and assessments + * wants to be able to use scores in order to quantitatively compare candidates * Contributed to DG for non-functional requirements -* Contributed to DG for use cases regarding to add and remark features + * Product Visuals should be `unambiguous` and clear to the user + * Commands should be `easy to remember` and `intuitive` to use + * Product should be `consistent` in its visuals and commands formatting +* Contributed to DG for use cases regarding `add`, `remark`, `view`, `Using scores to compare and filter people` * Contributed to DG for architecture diagram for UI, Storage, Model * Contributed to DG for feature implementation details for `view`. +* Contributed to DG for Activity and Sequence diagram for `view`. +* Contributed to DG for manual testing for `add`, `edit`, `view`, `filter`, `remark` features. + **Contribution to team-based tasks**: * Keeping track of deadlines and objectives @@ -68,16 +73,21 @@ In terms of the UG and DG, I have been in charge of the overall structure and fo * Managing the team's progress and ensuring that everyone is on track * In charge of overall UG and DG structure and formatting for the team - **Review/mentoring contributions**: * Reviewed PRs for team members - +* Helped team members with their issues and bugs. Especially with design issues and understanding of the code base. **Contributions beyond the project team**: -* Participated in the PE Dry Run and gave feedback to the other team +* Participated in the PE Dry Run and gave feedback to the other team (About 9 bugs reported, out of which there was 1 major over-arching bug that was reported) + +** Test Case Contributions**: +* Covered all the test cases for the commands that I have implemented. Contributed to the team's test case as well as AB3's test case. + ### Contributions to Developer Guide(Extracts) + + ### View feature #### Implementation @@ -139,6 +149,20 @@ Cons: You cannot implement any command that does not involve viewing but inherit An example could be trying to create identical commands that does not toggle the UI after execution. This would require duplication of the exact same command code but inheriting from `Command` instead of `ViewCommand`. +* wants an organized way to keep track of candidates information +* wants to view and manage candidates information in a single place +* wants to attach a score to candidate performance over interview and assessments +* wants to be able to use scores in order to quantitatively compare candidates + +| Priority | As a …​ | I want to …​ | So that…​ | +|----------|----------------|------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `* * *` | Hiring Manager | add a candidate's contact information, including name, email, phone number | I can easily access and reach out to candidates when needed | +| `* * *` | Hiring Manager | add notes and comments to candidate profiles to document interview feedback and impressions | I can maintain a record of interactions and feedback | +| `* * *` | Hiring Manager | view a specific job applicant's resume or portfolio | I can check whether they meet the requirements requested by other department heads | +| `* * *` | Hiring Manager | record the score of the different activities such as interviewsor assessments that an applicant might go through | I can use them for effective comparison and filter the candidates easily | +| `* * *` | Hiring Manager | compare candidates using their performance in their assessments or interviews | I can choose the best candidates to move to the next stage of the hiring process and get the best performing candidates objectively | + +### The remaining are the use cases for my features related and test cases for manual testing. ### Contributions to User Guide(Extracts) @@ -148,25 +172,24 @@ An example could be trying to create identical commands that does not toggle the 2. Overview of Main Features ### Adding an applicant: `add` + -Adds a person to JABPro. +Adds an applicant to JABPro. Format: `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/[CATEGORY] TAGNAME]…​` -Type | Prefix | Constraints -----------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------- -Mandatory | `n/NAME` | `NAME` must be alphanumeric (Letters and numbers, no symbols allowed such as `/`, `,` ...) -Mandatory| `p/PHONE_NUMBER` | `PHONE_NUMBER` must contain numbers only and should be at-least 3 digits long -Mandatory| `e/EMAIL` | `EMAIL` must be the standard email address format (There must be an email-prefix followed by `@` symbol and email domain) -Mandatory| `a/ADDRESS` | `ADDRESS` can be any value, including special characters such as `#`, `,` ... - Optional| `t/[CATEGORY] TAGNAME` | `TAGNAME` must be alphanumeric with no spaces. Any details after the space will be ignored. - - +| Type | Prefix | Constraints | +|-----------|------------------------|-----------------------------------------------------------------------------------------------------------------------------| +| Mandatory | `n/NAME` | `NAME` must be alphanumeric (Letters and numbers, no symbols allowed such as `/`, `,` ...). | +| Mandatory | `p/PHONE_NUMBER` | `PHONE_NUMBER` must contain numbers only and should be at-least 3 digits long. | +| Mandatory | `e/EMAIL` | `EMAIL` must be the standard email address format (There must be an email-prefix followed by `@` symbol and email domain). | +| Mandatory | `a/ADDRESS` | `ADDRESS` can be any value, including special characters such as `#`, `,` ... | +| Optional | `t/[CATEGORY] TAGNAME` | `TAGNAME` must be alphanumeric with no spaces. Any details after the space will be ignored. | **Notes regarding additional constraint on `add` command:** -* The uniqueness of the person is determined by the name only. This means that you cannot have 2 persons with the same name in the application book. +* The uniqueness of the applicant is determined by the name only. This means that you cannot have 2 applicants with the same name in the application book. * All other fields other than name can be identical between different people in JABPro. -* Persons added using the `add` command will be added to the end of the list. +* Applicants added using the `add` command will be added to the end of the list. **Notes on adding tags:** * If you would like to tag a user with a tag that has not been categorised yet using the `create` command, @@ -174,93 +197,105 @@ Mandatory| `a/ADDRESS` | `ADDRESS` can be any value, including speci * If you are using a tag that has not been categorised yet and you did not specify its category in the `add` command, the tag would still be saved but it would be "uncategorised" by default. * If you have multiple tags in different categories with the same name, you must specify the category when you want to - add one of these tags to the candidate you are adding. + add one of these tags to the applicant you are adding. **Tip:** -* A person can have any number of tags (including 0)! +* An applicant can have any number of tags (including 0)! - - An example of the `add` command being successfully executed: 1. Enter the command `add n/Betsy Crowe t/friend e/betsycrowe@example.com a/Newgate Prison p/1234567 t/dept finance` 2. This is the result of the successful `add` command (Take note that command entered will not be shown in the result): + ![Add-Success](images/add-command-success.png)
-An example of the `add` command failing to execute due to missing mandatory fields: -1. Enter the command `add n/Betsy Crowe t/friend` (**Missing mandatory fields**) -2. This is the result of the failed `add` command: - ![Add-Fail](images/add-command-failure.png) -
+**Error Handling Table for `add` command:** -An example of trying to add a person with the same name as an existing person: -1. Enter the command `add n/Betsy Crowe t/friend e/betsycrowe@example.com a/Newgate Prison p/1234567 t/dept finance` (**Same name as existing applicant**) -2. This is the result of the failed `add` command: - ![Add-Fail](images/add-command-duplicate-person.png) +| Reason for Error | Error Message | Remedy / Suggested course of action | +|-----------------------------------------------|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| +| Missing add keyword: `add` | Unknown command | Follow the command format of `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAGNAME]…​` closely | +| Missing mandatory fields | Invalid command format! | Ensure that all mandatory fields are filled up. | +| Duplicate name | This person already exists in the address book | Ensure that the name of the applicant is unique. That is you cannot add the same name twice. Use some form of extra identification like a number | +| Invalid phone number | Phone numbers should only contain numbers, and it should be at least 3 digits long | Ensure that the phone number only contains number and should be at least 3 digits long | +| Invalid email | Emails should be of the format local-part@domain and adhere to the following constraints:| Ensure that the prefix and domain of the email is correct following the constraints stated by the error | +| Invalid tag name | Tag names should only contain alphanumeric characters and should not be blank | Ensure that the tag name only contains alphanumeric characters and should not be blank | +| Multiple prefixes of the same type being used | Multiple values specified for the following single-valued field(s): `prefix/` | Remove the duplicate prefix. The command should only have 1 of every prefix except for `t/` | + +**Tip:** To know if it is an error, the command entered will light up in red. It remains in the command box. +1. The error message will be displayed in the result display box. +2. Follow the error handling table for the command or use the suggested course of action in the result display to rectify the error. + + -### Adding a remark to a applicant: `remark` +### Adding a remark to an applicant: `remark` + Edits a remark of an existing applicant in JABPro. Format: `remark INDEX r/REMARK` - -Type | Prefix | Constraints -----------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------- -Mandatory | `INDEX` | `INDEX` must be an existing index in the displayed applicant list -Optional | `r/ REMARK` | `REMARK` can be any value, including special characters such as `#`, `,` ... - +| Type | Prefix | Constraints | +|-----------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| Mandatory | `INDEX` | `INDEX` must be an existing index in the displayed applicant list and it must not be greater than the total number of applicants in JABPro. | +| Optional | `r/ [REMARK]` | `REMARK` can be any value, including special characters such as `#`, `,` ... | **Notes regarding `remark` command:** * The previous remark is not saved, and instead is replaced by the inputted remark. The command does not add to the existing remark. * You can empty out a remark by inputting `r/` without any text after it or by omitting the `r/` prefix. * You can get the remark previously inputted by using the **REMARK** keyword. It will be replaced with the previous remark. The keyword **REMARK** is case-sensitive. This means that `remark 1 r/**remark**` will just replace the remark with the word `**remark**`. +* You can use multiple prefix for `remark` but only the last prefix will be used. This means that `remark 1 r/remark r/remark2` will just replace the remark with `remark2`. + An example of the `remark` command being successfully executed: 1. Enter the command `remark 1 r/Great attitude, hardworking` 2. This is the result of the successful `remark` command (Take note that command entered will not be shown in the result): - ![Remark-Success](images/remark-command-success.png) -
+3. ![Remark-Success](images/remark-command-success.png) +
An example of the `remark` command being successfully executed with the **REMARK** keyword: 1. Enter the command `remark 1 r/**REMARK** furthermore he is great at teamwork` 2. This is the result of the successful `remark` command (Take note that command entered will not be shown in the result): + ![Remark-Success](images/remark-command-enhanced-success.png)
+**Error Handling Table for `remark` command:** +| Reason for Error | Error Message | Remedy / Suggested course of action | +|-----------------------------------------------|---------------------------------------|-------------------------------------------------------------------------------------------------| +| Missing remark keyword: `remark` | Unknown command | Follow the command format of `remark INDEX r/[REMARK]` closely | +| Missing Index | Invalid command format! | Ensure that the index is filled up. | +| Invalid Index | The person index provided is invalid | Ensure that the index is valid. That is it is a number that is on the displayed applicant list. | +| Negative or 0 Index | Invalid command format! | Ensure that the index is a positive integer and is also a number that is on the displayed applicant list. | + +**Tip:** To know if it is an error, the command entered will light up in red. It remains in the command box. +1. The error message will be displayed in the result display box. +2. Follow the error handling table for the command or use the suggested course of action in the result display to rectify the error. -An example of the `remark` command failing to execute due to wrong index: -1. Enter the command `remark 10 r/Great attitude, hardworking` (**Index does not exist on applicant list panel**) -2. This is the result of the failed `remark` command: - ![Remark-Fail](images/remark-command-clear-remark.png) -
- - - + Additional Examples: -* `remark 1` Empties the remark of the 1st person. It is equivalent to `remark 1 r/`. - +* `remark 1` Empties the remark of the 1st applicant. It is equivalent to `remark 1 r/`. -### Viewing a person's details: `view` +### Viewing a applicant's details: `view` + -Creates a complete view for details of an applicant in the second main panel and summary statistics (if applicable) of a candidate in the third main panel. +Creates a complete view for details of an applicant in the second main panel and summary statistics (if applicable) of an applicant in the third main panel. Format: `view INDEX` -Type | Prefix | Constraints -----------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------- -Mandatory | `INDEX` | `INDEX` must be an existing index in the displayed applicant list +| Type | Prefix | Constraints | +|-----------|---------|--------------------------------------------------------------------------------------------------------------------------------------------| +| Mandatory | `INDEX` | `INDEX` must be an existing index in the displayed applicant list and it must not be greater than the total number of applicant in JABPro. | **Notes regarding `view` command:** * The index used will be the same index as the one shown in the displayed applicant list. @@ -278,65 +313,91 @@ This means that the view will be updated to reflect the latest changes to the da An example of the `view` command being successfully executed: 1. Enter the command `view 3` 2. This is the result of the successful `view` command (Take note that command entered will not be shown in the result): - ![View-Success](../images/view-command-success.png) + + ![View-Success](images/view-command-success.png)
-An example of the `view` command being successfully executed for person with tags and score: -1. Enter the command `view 2` (**Person with tags and score**) +An example of the `view` command being successfully executed for applicant with tags and score: +1. Enter the command `view 2` (**Applicant with tags and score**) 2. This is the result of the successful `view` command (Take note that command entered will not be shown in the result): - ![View-Success](../images/view-command-with-stats-success.png) -
-An example of the `view` command failing to execute due to wrong index: -1. Enter the command `view 0` (**Index does not exist on applicant list panel**) -2. This is the result of the failed `view` command: - ![View-Fail](../images/view-command-failure.png) + ![View-Success](images/view-command-with-stats-success.png)
-### Editing a person : `edit` + +**Error Handling Table for `view` command:** + +| Reason for Error | Error Message | Remedy / Suggested course of action | +|-----------------------------------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| +| Missing view keyword: `view` | Unknown command | Follow the command format of `view INDEX` closely | +| Missing Index | Invalid command format! | Ensure that the index is filled up. | +| Invalid Index | The person index provided is invalid| Ensure that the index is valid. That is it is a number that is on the displayed applicant list. | + + + +**Tip:** To know if it is an error, the command entered will light up in red. It remains in the command box. +1. The error message will be displayed in the result display box. +2. Follow the error handling table for the command or use the suggested course of action in the result display to rectify the error. + + + + + +### Editing a applicant: `edit` + Edits an existing applicant's detail in JABPro Format: `edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAGNAME]…​ [sc/TAGNAME SCORE]` -Type | Prefix | Constraints -----------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------- -Mandatory | `INDEX` | `INDEX` must be an existing index in the displayed applicant list -Optional | `n/NAME` | `NAME` must be alphanumeric (Letters and numbers, no symbols allowed such as `/`, `,` ...) -Optional| `p/PHONE_NUMBER` | `PHONE_NUMBER` must contain numbers only and should be at-least 3 digits long -Optional| `e/EMAIL` | `EMAIL` must be the standard email address format (There must be an email-prefix followed by `@` symbol and email domain) -Optional| `a/ADDRESS` | `ADDRESS` can be any value, including special characters such as `#`, `,` ... -Optional| `t/TAGNAME` | `TAGNAME` must be alphanumeric with no spaces. Any details after the space will be ignored. -Optional| `sc/TAGNAME SCORE` . | `TAGNAME` a tag that is being created or already exist for that applicant. `SCORE` must be a non-negative integer. - +| Type | Prefix | Constraints | +|-----------|--------------------|-----------------------------------------------------------------------------------------------------------------------------| +| Mandatory | `INDEX` | `INDEX` must be a non-zero unsigned integer and must also not be greater than the total number of applicants in JABPro. | +| Optional | `n/NAME` | `NAME` must be alphanumeric (Letters and numbers, no symbols allowed such as `/`, `,` ...). | +| Optional | `p/PHONE_NUMBER` | `PHONE_NUMBER` must contain numbers only and should be at-least 3 digits long. | +| Optional | `e/EMAIL` | `EMAIL` must be the standard email address format (There must be an email-prefix followed by `@` symbol and email domain). | +| Optional | `a/ADDRESS` | `ADDRESS` can be any value, including special characters such as `#`, `,` ... | +| Optional | `t/TAGNAME` | `TAGNAME` must be alphanumeric with no spaces. Any details after the space will be ignored. | +| Optional | `sc/TAGNAME SCORE` | `TAGNAME` a tag that is being created or already exist for that applicant. `SCORE` must be a non-negative integer. | **Notes regarding `edit` command:** * At least one of the optional fields must be provided. * Existing attributes will be updated to the input values. * There is a way to edit tags and their categories at the same time. Look at the notes for editing tags with categories `t/[CATEGORY] TAGNAME` for more details. -**Notes on editing the tags of the specified person for `t/TAGNAME`**: -* When editing tags, the existing tags of the person will be removed i.e adding of tags is not cumulative. -* You can remove all the person’s tags by typing `t/` without +**Notes on editing the tags of the specified applicant for `t/TAGNAME`**: +* When editing tags, the existing tags of the applicant will be removed i.e adding of tags is not cumulative. +* You can remove all the applicant’s tags by typing `t/` without specifying any tags after it. -* There is no current way to keep the existing tags and add new tags to the person. You will have to re-tag the person with the existing tags and the new tags. - +* There is no current way to keep the existing tags and add new tags to the applicant. You will have to re-tag the applicant with the existing tags and the new tags. -**Notes on editing the score of the specified person for `sc/TAGNAME SCORE`**: +**Notes on editing the score of the specified applicant for `sc/TAGNAME SCORE`**: * The `TAG` in `sc/TAG SCORE` must be a tag of the category `assessment`. You cannot use the `sc/TAG SCORE` field for tags that are not of the `assessment` category. -* The `sc/TAG SCORE` field can only be used after the `t/TAG` field is used if the tag has not been created or the `TAG` already exist on the applicant -* The `SCORE` in `sc/TAG SCORE` is non-negative, that is `SCORE` must be more than or equal to 0 -* To clear a tag's score, just re-tag it with the same tag name, but without using the `sc/TAG SCORE` field +* The `sc/TAG SCORE` field can only be used after the `t/TAG` field is used if the tag has not been created or the `TAG` already exist on the applicant. +* The `SCORE` in `sc/TAG SCORE` is non-negative, that is `SCORE` must be more than or equal to 0. +* To clear a tag's score, just re-tag it with the same tag name, but without using the `sc/TAG SCORE` field. + + +Notes on rules for `edit` command involving tags with categories for `t/[CATEGORY] TAGNAME`: +* Consequently, similar rules for `add` apply to the `edit` command involving tags: + * If you would like to tag a user with a tag that has not been categorised yet using the `create` command, + you can specify the category that you would like it to be categorised to in the `edit` command. e.g. `edit 1 t/role swe` + * If you are using a tag that has not been categorised yet and you did not specify its category in the `add` command, + the tag would still be saved but it would be "uncategorised" by default. + * If you have multiple tags in different categories with the same name, you must specify the category when you want to + tag the specified applicant with one of these tags. 1. Editing an applicant's details will trigger a refresh of the view. This means that the view will be updated to reflect the latest changes to the data for that particular applicant. -2. We strongly recommend that you categorise tags using `create` before using `edit` to tag candidates. This is to reduce the confusion of having two ways to tag applicants. - +2. We strongly recommend that you categorise tags using `create` before using `edit` to tag applicants. This is to reduce the confusion of having two ways to tag applicants. + + An example of the `edit` command being successfully executed: 1. Enter the command `edit 1 n/Alex Ho p/91234567` (**Edit name and phone number**) 2. This is the result of the successful `edit` command (Take note that command entered will not be shown in the result): + ![Edit-Success](images/edit-command-success.png)
@@ -344,37 +405,54 @@ An example of the `edit` command being successfully executed with tags and score 1. Ensure that you have created a tag `Interview` under the `assessment` category using the `create` command. That is, enter the command `create t/assessment Interview` 2. Enter the command `edit 1 t/Interview sc/Interview 80` (**Edit tag and score**) 3. This is the result of the successful `edit` command (Take note that command entered will not be shown in the result): + ![Edit-Success](images/edit-command-with-stats-success.png)
- An example of the `edit` command being successfully executed to clear a tags and score: 1. Enter the command `edit 1 t/` (**Clear all tags**) 2. This is the result of the successful `edit` command (Take note that command entered will not be shown in the result): + ![Edit-Success](images/edit-command-clear-tags-success.png)
+**Error Handling Table for `edit` command:** + +| Reason for Error | Error Message | Remedy / Suggested course of action | +|-----------------------------------------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Missing edit keyword: `edit` | Unknown command | Follow the command format of `edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAGNAME]…​ [sc/TAGNAME SCORE]` closely | +| Missing Index | Invalid command format! | Ensure that the index is filled up. | +| Invalid Index | The person index provided is invalid | Ensure that the index is valid. That is it is a number that is on the displayed applicant list. | +| Missing at least one of the field | At least one field to edit must be provided. | Ensure that at least one of the field is filled up and to be changed. | +| Duplicate name | This person already exists in the address book | Ensure that the name of the applicant is unique. That is you cannot add the same name twice. Use some form of extra identification like a number | +| Invalid phone number | Phone numbers should only contain numbers, and it should be at least 3 digits long | Ensure that the phone number only contains number and should be at least 3 digits long | +| Invalid email | Emails should be of the format local-part@domain and adhere to the following constraints: | Ensure that the prefix and domain of the email is correct following the constraints stated by the error | +| Invalid tag name | Tag names should only contain alphanumeric characters and should not be blank | Ensure that the tag name only contains alphanumeric characters and should not be blank | +| Multiple prefixes of the same type being used | Multiple values specified for the following single-valued field(s): `prefix/` | Remove the duplicate prefix. The command should only have 1 of every prefix except for `t/` | +| Missing score for tag | Invalid score, score must be non-negative integer. | Ensure that the score is filled up and has a space from the `TAGNAME`. | +| Invalid tag to attach score | Invalid score tag, tag must a tag of the category assessment and must exist on the applicant | Ensure that the tag is of the category assessment and exist on the applicant. If its the wrong category, use `create`, if it is not tagged to the person use `edit` | -An example of the `edit` command being wrongly executed due to trying to attach a score to a tag that is not of the `assessment` category: -1. Enter the command `edit 1 t/TechLead sc/TechLead 80` (**Tag `TechLead` is not of the assessment category**) -2. This is the result of the failed `edit` command: - ![Edit-Fail](images/edit-command-failure.png) -
+ +**Tip:** To know if it is an error, the command entered will light up in red. It remains in the command box. +1. The error message will be displayed in the result display box. +2. Follow the error handling table for the command or use the suggested course of action in the result display to rectify the error. + ### Filter job applicants by statistics: `filter` + Filters and display applicants in the current displayed applicant list using statistical metrics and values. Format:`filter t/TAGNAME met/METRIC val/VALUE` or `filter t/TAGNAME met/METRIC` -Type | Prefix | Constraints -----------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------- -Mandatory | `t/TAGNAME` | `TAGNAME` must be a tag that is of the category `assessment` -Mandatory| `met/METRIC` | `METRIC` must be either `score`, `percentile`, `mean`, `median` -Optional| `val/VALUE` | Optional only for `mean` and `median`. Otherwise, VALUE` must be a non-negative integer and is a mandatory field. +| Type | Prefix | Constraints | +|-----------|--------------|--------------------------------------------------------------------------------------------------------------------| +| Mandatory | `t/TAGNAME` | `TAGNAME` must be a tag that is of the category `assessment`. | +| Mandatory | `met/METRIC` | `METRIC` must be either `score`, `percentile`, `mean`, `median`. | +| Optional | `val/VALUE` | Optional only for `mean` and `median`. Otherwise, `VALUE` must be a non-negative integer and is a mandatory field. | **Notes regarding `filter` command:** * Filter works only on the current list of job applicants displayed. It is essential that you enter `list` before using `filter` to ensure that you are filtering the correct list of job applicants. @@ -382,7 +460,7 @@ Optional| `val/VALUE` | Optional only for `mean` and `median`. Otherwi * Filters and displays job applicants whose **value** is **greater than or equal** to the specified value for the specified statistic metric. * For `METRIC` that is `mean` or `median`, the `VALUE` is optional. Specifying a `VALUE` here will be ignored accordingly. `filter t/TAGNAME met/METRIC` is equivalent to `filter t/TAGNAME met/METRIC val/X` where `X` is any positive integer. * Filter does not edit, update or in any way change the data of the job applicants. It only filters and displays the job applicants. -* Filter does not trigger view, that is your view panels represent the previous candidate you viewed before filtering. +* Filter does not trigger view, that is your view panels represent the previous applicant you viewed before filtering. * To get back the **original list with all the applicants**, simply type `list` again. **Notes on the different metrics:** @@ -403,6 +481,7 @@ Set up for examples when you first start JABPro with default data: 4. `edit 2 t/interview sc/interview 90` 5. `edit 3 t/interview sc/interview 70` 6. The result of the above commands should look like this: + ![Filter-Setup](images/filter-setup.png)
@@ -410,6 +489,7 @@ An example of the `filter` command being successfully executed: 1. Enter the command `list` 2. Enter the command `filter t/interview met/percentile val/80` (**Filter by percentile**) 3. This is the result of the successful `filter` command (Take note that command entered will not be shown in the result): + ![Filter-Success](images/filter-command-success.png)
@@ -417,27 +497,35 @@ An example of the `filter` command being successfully executed with `median`: 1. Enter the command `list` 2. Enter the command `filter t/interview met/median` (**Filter by median**) 3. This is the result of the successful `filter` command (Take note that command entered will not be shown in the result): + ![Filter-Success](images/filter-command-median-success.png)
-An example of the `filter` command being incorrectly executed due to non-existent tag: -1. Enter the command `list` -2. Enter the command `filter t/techlead met/percentile val/80` (**Tag `techlead` does not exist**) -3. This is the result of the failed `filter` command: - ![Filter-Fail](images/filter-command-failure.png) -
+**Error handling for `filter` command:** + +| Reason for Error | Error Message | Remedy / Suggested course of action | +|---------------------------------------------------------|--------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Missing filter keyword: `filter` | Unknown command! | Follow the command format strictly of `filter t/TAGNAME met/METRIC val/VALUE` for score and percentile or `filter t/TAGNAME met/METRIC` for mean or median. | +| Missing parameters | Incomplete parameter inputs. t/TAG and met/SCORE are compulsory fields. | Enter the command again with the correct parameters. | +| Invalid tag as tag has wrong category or does not exist | Tag does not exist! | Check that the tag is of the category `assessment` and that the tag exists using `listT`. Use the `create` command if it does not. | +| Invalid metric | Invalid metric provided. Needs to be one of: score, mean, median, percentile | Check that the metric is one of the following: `score`, `mean`, `median`, `percentile` and that it is spelt correctly. Enter the command again with any of the 4 metric | +| Invalid value | Invalid value provided. Needs to be a non negative integer that is more than or equal to 0 | Check that the value is a non-negative integer that is more than or equal to 0. Enter the command again with the correct value. | +| Missing value | val/VALUE is missing, it is compulsory. | Enter a value for `val/VALUE` since the metric requires it. | +| Multiple prefixes of the same type being used | Multiple values specified for the following single-valued field(s): `prefix/` | Remove the duplicate prefix. The command should only have 1 of every prefix | + + + + +**Tip:** To know if it is an error, the command entered will light up in red. It remains in the command box. +1. The error message will be displayed in the result display box. +2. Follow the error handling table for the command or use the suggested course of action in the result display to rectify the error. + + -An example of the `filter` command being incorrectly executed due to an invalid value for `val/VALUE`: -1. Enter the command `list` -2. Enter the command `filter t/interview met/percentile val/-1` (**Negative value for percentile**) -3. This is the result of the failed `filter` command: - ![Filter-Fail](images/filter-command-failure-2.png) -
**Significance of using `filter` with the metrics `score`, `percentile`, `mean` and `median`:** In essence, this allows you to find job applicants whose performance rating is above a certain percentile, score or mean/median score for that tag. -Ideally, this feature can then be used to find the best candidates easily and quickly without having to manually look through the list of candidates. - +Ideally, this feature can then be used to find the best applicants easily and quickly without having to manually look through the list of applicants. ## Summary Statistics @@ -445,49 +533,47 @@ Ideally, this feature can then be used to find the best candidates easily and qu Summary Statistics is a table generated by JABPro that displays the following information about an applicant: It is generated for tags that are categorised under the `assessment` category. - Statistic / Metric | Description ---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------- -`score` | The score of the candidate for the tag -`mean` | The mean score of candidates with that tag -`median` | The median score of candidates with that tag -`minimum` | The minimum score of candidates with that tag -`maximum` | The maximum score of candidates with that tag -`percentile` | The percentile of the candidate for that tag - - +| Statistic / Metric | Description | +|--------------------|-----------------------------------------------| +| `score` | The score of the applicant for the tag. | +| `mean` | The mean score of applicant with that tag. | +| `median` | The median score of applicant with that tag. | +| `minimum` | The minimum score of applicant with that tag. | +| `maximum` | The maximum score of applicant with that tag. | +| `percentile` | The percentile of the applicant for that tag. | -You should ensure that you have **sufficient candidates of more than 20** with a score for the tag you are interested in, before using the summary statistics to make comparisons. - -**Notes on why you should have sufficient candidates with a score for the tag you are interested in:** +You should ensure that you have **sufficient candidates of more than 20** with a score for the tag you are interested in, before using the summary statistics to make comparisons. + + +**Notes on why you should have sufficient applicants with a score for the tag you are interested in:** 1. This is due to the fact that these summary statistics rely on concepts such as mean, median and percentile, which are statistical concepts that require a sufficient sample size to be meaningful. -2. For example, if you have only assigned 5 out of 100 candidates, the summary statistics will not be representative of the actual mean, median and percentile for that tag. -3. In this case, you should assign more candidates with a score for that tag, before using the summary statistics to make comparisons. -5. If you have assigned a sufficient number of candidates with a score for that tag, you can use the summary statistics to make comparisons. For example, you want to check if a candidate's score for a tag is more than or equal to half of all the candidates who have a score for that tag, you can use the median to make this comparison. -* A **sufficient number** could be deemed as **any number that is more than 20**, but this is not a hard and fast rule. You should use your own discretion to determine if the number of candidates with a score for that tag is sufficient. +2. For example, if you have only assigned 5 out of 100 applicants, the summary statistics will not be representative of the actual mean, median and percentile for that tag. +3. In this case, you should assign more applicants with a score for that tag, before using the summary statistics to make comparisons. +4. If you have assigned a sufficient number of applicants with a score for that tag, you can use the summary statistics to make comparisons. For example, you want to check if an applicant's score for a tag is more than or equal to half of all the applicant who have a score for that tag, you can use the median to make this comparison. +* A **sufficient number** could be deemed as **any number that is more than 20**, but this is not a hard and fast rule. You should use your own discretion to determine if the number of applicant with a score for that tag is sufficient. -1. Use mostly `median` and `percentile` to make your judgement on the performance of a candidate. -2. `median` to find candidates who are the better performing half -3. `percentile` as where this candidate stands among all other candidates (treat it like a ranking system, the higher the percentile, the better the candidate is performing) +1. Use mostly `median` and `percentile` to make your judgement on the performance of an applicant. +2. `median` to find applicants who are the better performing half +3. `percentile` as where this applicant stands among all other applicants (treat it like a ranking system, the higher the percentile, the better the applicant is performing) - - **Advanced users** * Understand that `percentile` has limited functionality in some context. This is because if two applicants have the same score, they are `rank` the same. This means that the percentile of both applicants will be the same. - * If all applicants have the same score, their percentile will all be 0.0. This is because they are all `rank` the same. - * Additionally, when the spread of scores is small, the percentile will not be able to differentiate between applicants with similar scores. + * If all applicants have the same score, their percentile will all be 0.0. This is because they are all `rank` the same. + * Additionally, when the spread of scores is small, the percentile will not be able to differentiate between applicants with similar scores. **Formula used to calculate the summary statistics:** -**mean** is calculated by using the formula `sum of all scores with that tag/ number of candidates with that tag` +**mean** is calculated by using the formula `sum of all scores with that tag / number of applicants with that tag` **median** is calculated by using the formula `middle score of all scores with that tag` **minimum** is calculated by using the formula `lowest score of all scores with that tag` **maximum** is calculated by using the formula `highest score of all scores with that tag` -**percentile** is calculated by using the formula `number of candidates with a score strictly lower than the candidate/ total number of candidates with that tag` +**percentile** is calculated by using the formula `number of applicants with a score strictly lower than the applicant / total number of applicants with that tag` +