forked from nus-cs2103-AY2324S2/tp
-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #230 from willowisp01/ug-final
Ug final
- Loading branch information
Showing
1 changed file
with
64 additions
and
57 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -26,13 +26,13 @@ Happy teaching! | |
| - [3.1 Assumptions](#31-assumptions) | ||
| - [4. Purpose of User Guide (UG)](#4-purpose-of-user-guide-ug) | ||
| - [5. Quick Start](#5-quick-start) | ||
| - [6 Understanding our graphical user interface](#6-understanding-our-gui) | ||
| - [6. Understanding our graphical user interface](#6-understanding-our-gui) | ||
| - [7. Features](#7-features) | ||
| - [7.1 Viewing Help](#71-viewing-help--help) | ||
| - [7.2 Adding a student](#72-adding-a-student--add) | ||
| - [7.3 Listing all students](#73-listing-all-students--list) | ||
| - [7.4 Editing a student](#74-editing-a-student--edit) | ||
| - [7.5 Viewing a student](#75-viewing-students-by-name--view) | ||
| - [7.5 Viewing a student](#75-viewing-students--view) | ||
| - [7.6 Deleting a student](#76-deleting-a-student--delete) | ||
| - [7.7 Forming focus groups](#77-forming-focus-groups) | ||
| - [7.7.1 Forming focus groups manually](#771-forming-focus-groups-manually--group) | ||
|
|
@@ -47,7 +47,7 @@ Happy teaching! | |
| - [7.10.5 Clearing all entries](#7105-clearing-all-entries--clear_archived) | ||
| - [7.11 Exiting the program](#711-exiting-the-program--exit) | ||
| - [7.12 Saving data](#712-saving-the-data) | ||
| - [7.13 Editing the data file](#713-editing-the-data-file) | ||
| - [7.13 Editing the data file](#713-editing-the-data-files) | ||
| - [7.14 Setting a weak threshold](#714-setting-weak-threshold--setweak) | ||
| - [7.15 Viewing summary statistics](#715-viewing-summary-statistics--summary) | ||
| - [8. Glossary](#8-glossary) | ||
|
|
@@ -190,7 +190,7 @@ and ensure optimal utilization of the application's capabilities. | |
| * Extraneous parameters for commands that do not take in parameters (such as `help`, `list`, `exit`, `clear`, and `clear_archived`) will be ignored.<br> | ||
| e.g. if the command specifies `help 123`, it will be interpreted as `help`. | ||
|
|
||
| * Extraneous parameters for commands that do take in parameters (such as `delete` and `group`) will be ignored.<br> | ||
| * Extraneous parameters for commands that do take in parameters (such as `delete` and `group`) are invalid. This will cause the command to fail.<br> | ||
| e.g. command `delete A0123432A n/John` or `group gp/Group 3 id/A0123212A id/A4938274F n/John` is invalid. | ||
|
|
||
| * 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. | ||
|
|
@@ -233,29 +233,31 @@ Format: `help` | |
|
|
||
| ### 7.2 Adding a student : `add` | ||
|
|
||
| Adds student details to the `persons` list. | ||
| Adds student details to the `persons` list. Specifying a group is optional. | ||
|
|
||
|
|
||
| Format: `add id/STUDENT_ID n/NAME e/EMAIL g/GRADE [gp/GROUP_NAME]...` | ||
|
|
||
| * `NAME`, `STUDENT_ID`, `GRADE`, and `EMAIL` must be specified, `GROUP_NAME` is optional. | ||
| * `NAME`, `STUDENT_ID`, `GRADE`, and `EMAIL` must be specified. `GROUP_NAME` is optional. | ||
| * `NAME` is case-sensitive. | ||
| * e.g. `John Doe is different from john doe` | ||
| * `STUDENT_ID` should **start with A follow by 7 digits and ends with a letter [A-Z]**. | ||
| * e.g. `John Doe` is different from `john doe` | ||
| * `STUDENT_ID` should start with 'A', followed by 7 digits, and end with any capital letter. | ||
| * e.g. `A0123459X` | ||
| * `EMAIL` should be of the format **local-part@domain**. The local-part should only be in the **format of e/E follow by 7 digits from [0-9]**. The **domain name must end with a domain label u.nus.edu**. | ||
| * `EMAIL` should be of the format `username@domain`. The `username` should start with **e**, followed by 7 digits. The `domain` should be **u.nus.edu**. | ||
| * e.g. `[email protected]` | ||
| * `GRADE` should be one of the valid grades: **[A+, A, A-, B+, B, B-, C+, C, D+, D, F]**. | ||
| * `GROUP_NAME` must only contain alphanumeric characters and space, if you choose to specify a group. | ||
|
|
||
|
|
||
| Example: | ||
| * `add id/A0123459X n/John Doe e/[email protected] g/A` adds the student named John Doe with student_id "A0123459X", email "[email protected]" and grade "A" to the list. | ||
| * `add id/A0123459X n/John Doe e/[email protected] g/A` adds the student named John Doe with `STUDENT_ID` "A0123459X", `EMAIL` "[email protected]" and `GRADE` "A" to the list. | ||
|
|
||
| Expected output: | ||
|  | ||
|
|
||
| ### 7.3 Listing all students : `list` | ||
|
|
||
| Shows a list of all students, ordered by grades in descending order ie. **[F, D, D+, C, C+, B-, B, B+, A- A, A+]**. | ||
| Shows a list of all students, ordered by grades in descending order, i.e. **[F, D, D+, C, C+, B-, B, B+, A- A, A+]**. | ||
|
|
||
| Format: `list` | ||
|
|
||
|
|
@@ -264,37 +266,38 @@ Format: `list` | |
|
|
||
| ### 7.4 Editing a student : `edit` | ||
|
|
||
| Edits an existing student in the list of students. | ||
| Edits an existing student (as specified by `STUDENT_ID`) in the list of students. Existing fields are updated to match the specified input fields. | ||
|
|
||
| Format: `edit STUDENT_ID [id/STUDENT_ID] [n/NAME] [e/EMAIL] [g/GRADE] [gp/GROUP_NAME]...` | ||
|
|
||
| * Edits the student with the specified `STUDENT_ID`. | ||
| * The `STUDENT_ID` refers to the id corresponding to the student in the list. | ||
| * The `STUDENT_ID` is case-sensitive, must be a String starting with ‘A’ and ending with any letter, with a total length of 9 | ||
| * The student with the specified `STUDENT_ID` must exist in the list. | ||
| * Existing value will be updated to the input value. | ||
| * `NAME` is case-sensitive, eg. john doe is different from John Doe | ||
| * Email must have the correct domain (@u.nus.edu) and string length of 8 for the email username eg. [email protected] | ||
| * `STUDENT_ID` should start with 'A', followed by 7 digits, and end with any capital letter. | ||
| * e.g. `A0123459X` | ||
| * `NAME` is case-sensitive. | ||
| * e.g. `John Doe` is different from `john doe` | ||
| * `EMAIL` should be of the format `username@domain`. The `username` should start with **e**, followed by 7 digits. The `domain` should be **u.nus.edu**. | ||
| * e.g. `[email protected]` | ||
| * `GRADE` should be one of the valid grades: **[A+, A, A-, B+, B, B-, C+, C, D+, D, F]**. | ||
| * The student with the specified `STUDENT_ID` must exist in the list. | ||
| * Editing `GROUP` will overwrite existing `GROUP` entries. | ||
| * Use of `GROUP` prefix `gp/` in an edit command without specifying `GROUP_NAME` will clear all existing `GROUP` of the student. | ||
|
|
||
| Examples: | ||
| * `edit A0123459X e/[email protected]` Edits the email address of the student with student_id = A0123459X to be `[email protected]`. | ||
| * `edit A0123459X n/John Doe` Edits the name of the student with student_id = A0123459X to be `John Doe`. | ||
| * `edit A0123459X e/[email protected]` Edits the email address of the student with `STUDENT_ID = A0123459X` to be `[email protected]`. | ||
| * `edit A0123459X n/John Doe` Edits the name of the student with `STUDENT_ID = A0123459X` to be `John Doe`. | ||
|
|
||
| Expected output: | ||
|  | ||
|
|
||
| ### 7.5 Viewing students : `view` | ||
|
|
||
| Shows the detailed information of the student with the specified student_id. | ||
| Shows the detailed information of the student with the specified `STUDENT_ID`. | ||
|
|
||
| Format: `view STUDENT_ID` | ||
|
|
||
| * Returns the detailed information of the student with the corresponding `STUDENT_ID`. | ||
| * The `STUDENT_ID` is case-sensitive. | ||
| * The `STUDENT_ID` starts with A, ends with a letter, and it must be 9 characters long. | ||
| * `STUDENT_ID` should start with 'A', followed by 7 digits, and end with any capital letter. | ||
| * e.g. `A0123459X` | ||
| * This feature is not applicable to the archived list, i.e. you can only view current students. | ||
|
|
||
| Examples: | ||
|
|
@@ -306,10 +309,11 @@ Deletes the specified student from the list. | |
|
|
||
| Format: `delete STUDENT_ID` | ||
|
|
||
| * Deletes the student at the specified `STUDENT_ID`. | ||
| * Deletes the student with the specified `STUDENT_ID`. | ||
| * The `STUDENT_ID` refers to the id corresponding to the student in the list. | ||
| * The `STUDENT_ID` is case-sensitive, must be a String starting with ‘A’ and ending with any letter, with a total length of 9 | ||
| * The student with the specified `STUDENT_ID` must exists in the list. | ||
| * `STUDENT_ID` should start with 'A', followed by 7 digits, and end with any capital letter. | ||
| * e.g. `A0123459X` | ||
| * The student with the specified `STUDENT_ID` must exist in the list. | ||
|
|
||
|
|
||
| Examples: | ||
|
|
@@ -321,11 +325,10 @@ Expected output: | |
| ### 7.7 Forming focus groups | ||
|
|
||
| #### 7.7.1 Forming focus groups manually : `group` | ||
| Creates a group with people corresponding to the selected IDs. | ||
| Creates a group with students corresponding to the selected IDs. | ||
|
|
||
| Format: `group gp/GROUP_NAME… id/STUDENT_ID…` (multiple groups, IDs allowed) | ||
| Format: `group gp/GROUP_NAME… id/STUDENT_ID…` | ||
|
|
||
| * Forms a group with the specified `GROUP_NAME`. | ||
| * The group name includes students with the corresponding `STUDENT_IDs`. | ||
| * If any of the given `STUDENT_IDs` do not exist, the command completely fails. | ||
| * `GROUP_NAME` cannot be empty, and must only contain alphanumeric characters and space. | ||
|
|
@@ -356,7 +359,7 @@ Examples: | |
| * Group formed cannot be deleted individually unless using the [`group` command](#771-forming-focus-groups-manually--group) to clear all groups <br> | ||
| eg. `group id/A0123459X` removes student with `STUDENT_ID = A0123459X` from all the groups the student was in. | ||
| * Random groups formed will not be affected by the [`setweak` command](#714-setting-weak-threshold--setweak)<br> | ||
| ie. student in a randomly formed group will remain in the group after `setweak` command, even if the student falls above the new weak threshold | ||
| i.e. student in a randomly formed group will remain in the group after `setweak` command, even if the student falls above the new weak threshold | ||
|
|
||
| </div> | ||
|
|
||
|
|
@@ -385,17 +388,17 @@ Format: `clear` | |
| ### 7.10 Archiving Features | ||
| #### 7.10.1 Archiving a student : `archive` | ||
|
|
||
| Archives a student from the `persons` list to the archived list. | ||
| Archives a student from the `persons` list. That student is moved to the archived list. | ||
|
|
||
| Format: `archive STUDENT_ID` | ||
|
|
||
| * Archives a student with the specified `STUDENT_ID`. | ||
| * `Student_ID` should **start with A follow by 7 digits and ends with a letter [A-Z]**. | ||
| * `STUDENT_ID` should start with 'A', followed by 7 digits, and end with any capital letter. | ||
| * e.g. `A0123459X` | ||
| * The student with the specified `STUDENT_ID` must exists in the `persons` list. | ||
| * The student with the specified `STUDENT_ID` must exist in the `persons` list. | ||
|
|
||
| Example: | ||
| * `archive A0123459X` archives a student with the student_id "A0123459X". | ||
| * `archive A0123459X` archives a student with `student_id = A0123459X`. | ||
|
|
||
| Expected output: | ||
|  | ||
|
|
@@ -408,18 +411,21 @@ Format: `edit_archived STUDENT_ID [id/STUDENT_ID] [n/NAME] [e/EMAIL] [g/GRADE] [ | |
|
|
||
| * Edits the details of an archived student with the specified `STUDENT_ID`. | ||
| * At least one of the optional fields indicated within the square bracket must be provided. | ||
| * The student with the specified `STUDENT_ID` must exists in the archived list. | ||
| * `Student_ID` should **start with A follow by 7 digits and ends with a letter [A-Z]**. | ||
| * e.g. `A0123459X` | ||
| * `NAME` is case-sensitive, eg. john doe is different from John Doe. | ||
| * Email must have the correct domain (@u.nus.edu) and string length of 8 for the email username eg. [email protected] | ||
| * The `...` after the `GROUP_NAME` indicates that multiple `GROUP_NAME`s can be provided for editing. | ||
| * The student with the specified `STUDENT_ID` must exist in the archived list. | ||
| * `STUDENT_ID` should start with 'A', followed by 7 digits, and end with any capital letter. | ||
| * e.g. `A0123459X` | ||
| * `EMAIL` should be of the format `username@domain`. The `username` should start with **e**, followed by 7 digits. The `domain` should be **u.nus.edu**. | ||
| * e.g. `[email protected]` | ||
| * `NAME` is case-sensitive. | ||
| * e.g. `John Doe` is different from `john doe` | ||
| * `GRADE` should be one of the valid grades: **[A+, A, A-, B+, B, B-, C+, C, D+, D, F]**. | ||
| * Editing `GROUP` will overwrite existing `GROUP` entries. | ||
| * Use of `GROUP` prefix `gp/` in an edit command without specifying `GROUP_NAME` will clear all existing `GROUP` of the student. | ||
| * *Use of `GROUP` prefix `gp/` in an edit command without specifying `GROUP_NAME` will clear all existing `GROUP`s of the student!* | ||
| * This feature is only applicable to the archived list. | ||
|
|
||
| Examples: | ||
| * `edit_archived A0123459X g/B e/[email protected]` edits the grade of the student with student_id "A0123459X" to "B" and the email to "[email protected]". | ||
| * `edit_archived A0123459X g/B e/[email protected]` edits the grade of the student with `STUDENT_ID = A0123459X` to "B" and the `EMAIL` to "[email protected]". | ||
|
|
||
| Expected output: | ||
|  | ||
|
|
@@ -431,31 +437,31 @@ Deletes an archived student from the archived list. | |
| Format: `delete_archived STUDENT_ID` | ||
|
|
||
| * Deletes an archived student with the specified `STUDENT_ID`. | ||
| * `Student_ID` should **start with A follow by 7 digits and ends with a letter [A-Z]**. | ||
| * `STUDENT_ID` should start with 'A', followed by 7 digits, and end with any capital letter. | ||
| * e.g. `A0123459X` | ||
| * The student with the specified `STUDENT_ID` must exists in the archived list. | ||
| * The student with the specified `STUDENT_ID` must exist in the archived list. | ||
| * This feature is only applicable to the archived list. | ||
|
|
||
| Example: | ||
| * `delete_archived A0123459X` deletes the student with student_id "A0123459X" from the archived list. | ||
| * `delete_archived A0123459X` deletes the student with `STUDENT_ID = A0123459X` from the archived list. | ||
|
|
||
| Expected output: | ||
|  | ||
|
|
||
| #### 7.10.4 Unarchiving a student : `unarchived` | ||
|
|
||
| Unarchives a student from the archived list to the `persons` list. | ||
| Unarchives a student from the archived list. That student is moved to the `persons` list. | ||
|
|
||
| Format: `unarchived STUDENT_ID` | ||
|
|
||
| * Unarchives a student with the specified `STUDENT_ID`. | ||
| * `Student_ID` should **start with A follow by 7 digits and ends with a letter [A-Z]**. | ||
| * `STUDENT_ID` should start with 'A', followed by 7 digits, and end with any capital letter. | ||
| * e.g. `A0123459X` | ||
| * The student with the specified `STUDENT_ID` must exists in the archived list. | ||
| * The student with the specified `STUDENT_ID` must exist in the archived list. | ||
| * This feature is only applicable to the archived list. | ||
|
|
||
| Examples: | ||
| * `unarchived A0123459X` unarchives a student with the student_id "A0123459X". | ||
| * `unarchived A0123459X` unarchives a student with the `student_id = A0123459X`. | ||
|
|
||
| Expected output: | ||
|  | ||
|
|
@@ -484,17 +490,17 @@ TeachStack data is saved automatically as a JSON file `[JAR file location]/data/ | |
|
|
||
| <div markdown="span" class="alert alert-warning">:exclamation: **Caution:** | ||
| If your changes to the data files makes its format invalid, TeachStack will discard all data and start with an empty data file at the next run. Hence, it is recommended to take a backup of the file before editing it.<br> | ||
| Furthermore, certain edits can cause the TeachStack to behave in unexpected ways (e.g., if a value entered is outside of the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly. | ||
|
|
||
| Furthermore, certain edits can cause the TeachStack to behave in unexpected ways (e.g., if a value entered is outside of the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly. **Teachstack cannot take any responsibility for corrupted data if you choose to modify the data files directly.** | ||
| </div> | ||
|
|
||
| ### 7.14 Setting weak threshold : `setweak` | ||
|
|
||
| Sets the weakness threshold for a weak marker. | ||
| Sets the weakness threshold for a weak marker. The weakness threshold is the minimum grade for a student to be considered weak. | ||
|
|
||
| Format: `setweak g/GRADE` | ||
|
|
||
| * By default, weakness threshold is set at Grade: C+ | ||
| * Updates weakness threshold value | ||
| * By default, weakness threshold is set to `GRADE = C+`. | ||
| * Students with grade lower or equal to threshold grade appear with a marker in the UI | ||
| * `GRADE` should be one of the valid grades: **[A+, A, A-, B+, B, B-, C+, C, D+, D, F]**. | ||
| * After setting the threshold, it will be maintained even after shutting down the application. | ||
|
|
@@ -535,8 +541,8 @@ Displayed after command: `summary` | |
| * **Grade**: A letter that shows how good a student's performance is. `TeachStack` only accepts grades that exist in the NUS grading system (**[A+, A, A-, B+, B, B-, C+, C, D+, D, F]**). | ||
| * **Name**: Name of a student. `TeachStack` only accepts name consisting of alphabets, numbers and space. | ||
| * **Focus group**: Group of students such that the user can pay more attention to assist the students in the group. Indicated by a `Group label` on the GUI | ||
| * **Student details**: The student's name, id, email address, grade, and focus group that the student belongs in if any. | ||
| * **Grade threshold**: A threshold used by the system to determine if a student is considered as `weak` based on grades. If the student's grade falls below or is at the threshold, the student is considered as weak. It is set to **C+** by default and user can update using the `setweak` command to set expected performance. | ||
| * **Student details**: The student's `NAME`, `STUDENT_ID`, `EMAIL`, `GRADE`, and focus group (`GROUP`) that the student belongs to, if any. | ||
| * **Grade threshold**: A threshold used by the system to determine if a student is considered as `weak` based on their grades. If the student's grade falls below, or is at the threshold, the student is considered as weak. It is set to **C+** by default. The user can update the threshold using the `setweak` command according to their preference. | ||
| * **Summary statistics**: Statistics of all active students (not in archived list), including the total number of students, mean grade, standard deviation of grade and a pie chart showing grade distribution. | ||
|
|
||
| -------------------------------------------------------------------------------------------------------------------- | ||
|
|
@@ -557,19 +563,20 @@ Displayed after command: `summary` | |
| **Q**: Is TeachStack suitable for Teaching Assistants (TAs)?<br> | ||
| **A**: While TeachStack is currently tailored for computer science instructors to simplify managing large student bodies, TAs may also find our app useful, especially in scenarios with larger class sizes. We continually strive to expand TeachStack's capabilities to better serve the diverse needs of educators and teaching teams. | ||
|
|
||
| **Q**: Is TeachStack really better than Canvas, Excel, etc. for me? | ||
| **Q**: Is TeachStack really better than Canvas, Excel, etc. for me?<br> | ||
| **A**: Yes! While the other platforms do offer valuable features, TeachStack stands out with its CLI, intuitive group forming, archiving, and other tailored features designed specifically for computer science educators. What sets TeachStack apart is our commitment to continuous improvement and development, driven by your feedback. With ongoing enhancements, we're dedicated to ensuring TeachStack remains the preferred choice for instructors seeking to elevate their teaching experience. | ||
|
|
||
| ### 9.2 Using TeachStack | ||
|
|
||
| **Q**: How do I transfer my data to another computer?<br> | ||
| **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 TeachStack home folder. | ||
|
|
||
| **Q**: I made changes to the data files manually and I am now facing errors! What should I do? | ||
| **Q**: I made changes to the data files manually and I am now facing errors! What should I do?<br> | ||
| **A**: We recommend that you only manually edit the files if you are confident that you can update it correctly. In the event that you run into errors after manually editing the files, please delete the `[JAR file location]/data` folder so TeachStack can create new files. | ||
|
|
||
| **Q**: Do I have to save my changes manually? | ||
| **Q**: Do I have to save my changes manually?<br> | ||
| **A**: No, TeachStack will automatically save any changes you have made after a command is entered. | ||
|
|
||
| -------------------------------------------------------------------------------------------------------------------- | ||
|
|
||
| ## 10. Known issues | ||
|
|
||