diff --git a/docs/UserGuide.md b/docs/UserGuide.md index a1fe3d2878d..5bdf4f4dcb1 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -8,42 +8,104 @@ TAHelper is a **desktop app for managing contacts, optimized for use via a Line Interface** (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, TAHelper can get your students' contact management tasks done faster than traditional GUI apps. +- For some uncommon or unfamiliar terms used in this User Guide, [click here](#glossary) for the definition and explanation of some. + +## Why choose TAHelper? + +## Table of contents - --- ## Target Audience -TAHelper is specifically designed to assist and help Teaching Assistants (TA) of NUS Computer Science Modules, +- TAHelper is specifically designed to assist and help Teaching Assistants (TA) of NUS Computer Science Modules, which caters to their need to store information in a way that is easy to track and visualise, as well as keep student's details in a centralised storage. Our target audience is specifically only TAs of NUS Computer Science Modules. ## Purpose of User Guide +- The purpose of the User Guide (UG) for TAHelper is to provide our target users, TAs of NUS Computer Science modules, with a comprehensive resource that +helps user effectively use and understand our application. In the User Guide, we display clear instructions, a quick start guide, and explanations to help users use TAHelper seamlessly +and effectively. This help users learn the new system in an extremely short timeframe, while allowing them to understand this application deeply, optimise their workflows and improve their +student contact management in the classes they teach. + +## Navigating the User Guide +Welcome to the TAHelper User Guide! Our goal is to assist and provide you the luxury of information, knowledge and utmost +confidence to make full use of TAHelper's features. + +- Effortless Navigation: [Refer here](#table-of-contents) for the table of contents to aid your navigation. +- Quick start guide for New Users: If you're a new user, visit our [Quick Start](#quick-start) section to set up and launch the application! +- Features: Want to leverage the capabilities of TAHelper? Visit our [Features](#features) section to fully utilise the features we offer! ## Quick start -1. Ensure you have Java `11` or above installed in your Computer. +1. Ensuring the correct version of Java installed: + - Ensure you have Java `11` or above installed in your Computer. + + +2. Download TAHelper from [here](https://github.com/AY2324S2-CS2103T-T09-4/tp/releases) + - Download the latest `tahelper.jar`. + + +3. Set up your application environment + - Copy the file `tahelper.jar` to the folder you want to use as the _home folder_ for your TAHelper. + - Tip: name that folder `TAHelper` to facilitate organisation and easy access. + + +4. Using the Terminal to run the application + - Windows OS: + - Press the windows button and type `cmd` into the search bar. + - It should look something like this: + - ![cmd](images/cmdguidewin.png) + + - Mac OS: + - Search for Terminal in "Utilities" under "Applications". + - It should look something like this: + - + + +5. Launching TAHelper + - `cd` into the folder you put the jar file in + - Type `java -jar tahelper.jar` command and hit Enter to run TAHelper.
+ - It should look something like this (in this case my jar file is in a folder called tahelper): + - ![cmd](images/cmdguidewin2.png) + + - A GUI similar to the below should appear in a few seconds.
+ - ![Ui](images/Ui.png) (to update!!). + + +6. Here are some commands to try out to get a feel of a TAHelper! type them in the Command box + - `/add_student name/Dohn Joe email/johndoe@gmail.com id/A0123456A`: Adds a new student contact with the name, email and ID specified. + - A new student entry should appear on the UI with the details reflected clearly. + + - `/delete_student id/A0123456A or /delete_student email/johndoe@gmail.com`: Deletes the student that you have add with the previous command. + - The student entry with the ID `A0123456A` or email `johndoe@gmail.com` will be deleted. + - This deletion will be reflected on User Interface of TAHelper as well. -1. Download the latest `tahelper.jar` from [here](https://github.com/AY2324S2-CS2103T-T09-4/tp/releases). + - For more Commands that will improve your experience, ![click here] -1. Copy the file to the folder you want to use as the _home folder_ for your TAHelper. +## Navigating the GUI -1. Open a command terminal, `cd` into the folder you put the jar file in, and use the `java -jar tahelper.jar` command to run the application.
- A GUI similar to the below should appear in a few seconds. Note how the app contains some sample data.
- ![Ui](images/Ui.png) +GUI Components -1. Type the command in the command box and press Enter to execute it. e.g. typing **`list_student`** and pressing Enter will display a list of students.
- Some example commands you can try: - - `/add_student name/Dohn Joe email/johndoe@gmail.com id/A0123456A module/CS2103T class/T09` : Adds a new student contact with all the details that have been specified to the relevant module and tutorial class. - - `/delete_student id/A0259209B | /delete_student email/johndoe@gmail.com` : Deletes a student contact with email `johndoe@gmail.com` or id `A0259209B`. +Commands on students: - - `/search_student id/A0123456A` : Searches for a student with id `A0123456A`. + - `/add_student name/Dohn Joe email/johndoe@gmail.com id/A0123456A`: Adds a new student contact with all the details. + + - `/delete_student id/A0259209B or /delete_student email/johndoe@gmail.com` : Deletes a student contact with email `johndoe@gmail.com` or id `A0259209B`. + + - `/search_student id/A0123456A or /search_student email/johndoe@gmail.com` : Searches for a student with id `A0123456A` or email `johndoe@gmail.com`. - `/list_student` : View the list of all students available. + - `/allocate_teams id/A1234567Z module/CS2101 tutorial/T01 name/team1` : Allocate a student to the specified team `team1` in the tutorial class `T01` of module `CS2101`. + + - `/add_student_to_class id/A1234567Z module/CS2101 tutorial/T01` : Add a student the tutorial class `T01` of module `CS2101`. + +Commands on modules: + - `/add_class module/CS2103T class/T09` : Adds a new tutorial class `T09` under the module `2103T`. - `/delete_class module/CS2103T class/T09` : Deletes a tutorial class `T09` under the module `2103T`. @@ -59,6 +121,10 @@ details in a centralised storage. Our target audience is specifically only TAs o **Notes about the command format:**
+### Command Format +Here are the main components of the commands: + +Here are symbols used in the commands: - Words in `UPPER_CASE` are the parameters to be supplied by the user.
e.g. in `add name/NAME`, `NAME` is a parameter which can be used as `add name/John Doe`. @@ -77,29 +143,29 @@ details in a centralised storage. Our target audience is specifically only TAs o ### Adding new students : `add_student` -Adds a new student contact with all the details that have been specified by the user to the relevant module and tutorial class +Adds a new student contact with all the details that have been specified by the user. -Format: `/add_student name/NAME email/EMAIL id/STUDENT_ID module/MODULE_CODE tutorial/TUTORIAL_CLASS` +Format: `/add_student name/NAME email/EMAIL id/STUDENT_ID` - The following parameters to add a student contact are supported: - 1. Name + 1. Name 2. Email 3. Student ID - 4. Module Code - 5. Tutorial class +- All fields must be specified - Leading/trailing spaces are removed - The parameter is case-insensitive - If none of the parameters or an invalid parameter is specified, the command will return an error message indicating that a valid parameter must be provided. -- For V1.2, we will only be adding students to their respective tutorial group. Instead, what happens is that we will add all the students to the respective module headers. Expected output: Upon a successful add, the command will return a confirmation messaging stating that the specified student contact has been added. -Examples: +Example: + +- `/add_student name/Dohn Joe email/johndoe@gmail.com id/A0123456A` -- `/add_student name/Dohn Joe email/johndoe@gmail.com id/A0123456A module/CS2103T tutorial/T09` +Explanation: This adds a student with name `Dohn Joe`, email `johndoe@gmail.com` and ID `A0123456A` into the TAHelper system. ### Deleting students : `delete_student` @@ -148,6 +214,49 @@ Format: `/list_student` Expected output: The command will display the list of all students along with their student information. If there are no existing students, the command will return a message indicating that there are no students currently. + +### Allocating students to tutorial teams : `allocate_team` + +Allocates a student to an existing tutorial team within a tutorial class. + +List of acceptable formats:
+ 1. `/allocate_team id/ID module/MODULE tutorial/TUTORIAL team/TEAMNAME`
+ 2. `/allocate_team email/EMAIL module/MODULE tutorial/TUTORIAL team/TEAMNAME`
+ 3. `/allocate_team index/INDEX module/MODULE tutorial/TUTORIAL team/TEAMNAME`
+ +- All fields from any acceptable formats have to be specified. +- Leading/trailing spaces are removed. +- A student cannot be added to the same tutorial team, under the same module and tutorial class, more than once. +- The index specified is with respect to the index of the student in the tutorial class. + +Pre-conditions: +1. The student you want to add has to already exist in the TAHelper system. +2. The tutorial class has to be associated and exist in the module specified. +3. The student you want to add has to already exist in the tutorial class specified. +4. The team you want to allocate the student into has to already exist within the specified tutorial class. + +Important note: +- Specifying more than one way to allocate student such as `/allocate_team id/ID email/EMAIL module/MODULE tutorial/TUTORIAL team/TEAMNAME` is not advised.
+This is because TAHelper will prioritise looking for the student that matches the ID specified rather than the email specified. This prioritisation is a feature of the system. + +Expected output: +Upon a successful allocation, the command will return a confirmation message stating that the specified student contact has been allocated to the tutorial team. + +Examples: +1. `/allocate_team id/A1234567Z module/CS2101 tutorial/T01 team/team1`
+ +Explanation: This allocates a student with ID matching `A1234567Z` in the tutorial class `T01` to a tutorial team `team1` of the tutorial class `T01` under the module `CS2101`. + +2. `/allocate_team email/johndoe@gmail.com module/CS2101 tutorial/T01 team/team2`
+ +Explanation: This allocates a student with email matching `johndoe@gmail.com` in the tutorial class `T01` to a tutorial team `team1` of the tutorial class `T01` under the module `CS2101`. + +3. `/allocate_team index/1 module/CS2101 tutorial/T01 team/team1`
+ +Explanation: This allocates a student with index position `1` in the tutorial class `T01` to a tutorial team `team1` of the tutorial class `T01` under the module `CS2101`. + + + ### Adding new tutorial class : `add_class` Adds a tutorial class with the specified module code and name. @@ -226,8 +335,31 @@ Examples: - Without team size:`/add_team module/CS2103T class/T10 name/Team 1` - With team size: `/add_team module/CS2103T class/T10 name/Team 1 size/3` ---- +### Randomly allocate into teams all students in a tutorial class : `random_teams` + +Randomly allocates all students in a tutorial class into different teams in the tutorial class. + +Format: `/random_teams module/MODULE tutorial/TUTORIAL teams/NUMBEROFTEAMS` + +- All fields from any acceptable formats have to be specified. +- Leading/trailing spaces are removed. + +Important Note: +- The number of teams cannot be more than the number of students in the tutorial class. +- The tutorial class have to be associated with the module specified. +- The number of teams must be a non-negative integer value. + +Expected output: +Upon a successful randomisation, the command will return a confirmation message stating that the students in the specified tutorial class has been randomly distributed into different teams in the tutorial class. + +Example: +- `/random_teams module/CS2101 tutorial/T01 teams/2` + +Explanation: This randomly allocates all the students in the tutorial class `T01` of module `CS2101` into 2 teams. + + +--- ## FAQ **Q**: How do I transfer my data to another Computer?
@@ -241,6 +373,18 @@ Examples: --- +### Glossary + +| Term | Definition and/or Explanation | +|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **OS** | Refers to Operating System. Modern Operating System include Windows, Macs and Linux. | +| **TA (Teaching Assistant)** | An individual who is responsible for teaching a tutorial class of University students. | +| **TAHelper** | A contact management application to help TAs keep track of students in classes they teach. | +| **Graphical User Interface (GUI)** | is a type of interface that allows users to interact with electronic devices through graphical icons and visual indicators,
as opposed to text-based interfaces, typed command labels, or text navigation. | +| **Command Line Interface (CLI)** | is a text-based user interface used to interact with software, through the use of key words command such as 'cd'. | + +--- + ## Command summary | Action | Format, Examples | diff --git a/docs/images/cmdguidewin.png b/docs/images/cmdguidewin.png new file mode 100644 index 00000000000..76e3fec7387 Binary files /dev/null and b/docs/images/cmdguidewin.png differ diff --git a/docs/images/cmdguidewin2.png b/docs/images/cmdguidewin2.png new file mode 100644 index 00000000000..e2c5b1ba279 Binary files /dev/null and b/docs/images/cmdguidewin2.png differ