From 8d728a88bdfa4335a073bd2cc3a8ca5615ec96dd Mon Sep 17 00:00:00 2001 From: ForAeons Date: Wed, 10 Apr 2024 17:53:54 +0800 Subject: [PATCH] Improve ug with FAQ and update keywords --- docs/UserGuide.md | 150 ++++++++++++++++++++++------------------------ 1 file changed, 73 insertions(+), 77 deletions(-) diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 77b454cf51c..1b67af9414e 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -61,57 +61,57 @@ Diving into TAPro, you'll encounter some handy notations and terms. We've decode ### Symbols -| Symbol | Meaning | -|------------------------------------------------------|--------------------------------------------------------| -| | Tip | -| | Warning | -| | Important | -| | Additional useful information | -| | Valid Example | -| | Invalid Example | -| | Danger | -| | Definition | -| | Question | -| **`UPPER_CASE`** | Represents parameters that need to be given by you! | +| Symbol | Meaning | +|------------------------------------------------------|-----------------------------------------------------------------| +| | Tip | +| | Warning | +| | Important | +| | Additional useful information | +| | Valid Example | +| | Invalid Example | +| | Danger | +| | Definition | +| | Question | +| **`UPPER_CASE`** | Represents parameters that need to be given by you! | | **... (Ellipsis)** | Indicates that a parameter can be repeated or omitted entirely. | -| **[Square Brackets]** | Denotes optional parameters. | +| **[Square Brackets]** | Denotes optional parameters. | ### Keywords -| Keywords | Meaning | -|------------------------------------|------------------------------------------------------------------------------------------| -| **Command Line Interface** | A text-based interface used for entering commands directly. | -| **Graphical User Interface** | The visual interface that enhances user interaction with graphical elements. | -| **Parameters** | Specific pieces of information required by commands to execute a function. | -| **Attribute** | A single detail of a student. | -| **INDEX** | A case-insensitive, unique identification code assigned to each student. | -| **NUSNET** | A unique identification code assigned to each student. | -| **TAG** | A one-word, case-insensitive, label that can be associated with a student for categorization. | -| **Autocomplete** | A feature that predicts and completes commands as you type. | -| **Command History** | A record of successfully executed commands that can be retrieved for reuse. | +| Keywords | Meaning | +|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Command Line Interface** | A text-based interface used for entering commands directly. | +| **Graphical User Interface** | The visual interface that enhances user interaction with graphical elements. | +| **Parameters** | Specific pieces of information required by commands to execute a function. | +| **Attribute** | A single detail of a student. | +| **INDEX** | A case-insensitive, unique identification code assigned to each student. | +| **NUSNET** | A unique identification code assigned to each student. | +| **TAG** | A one-word, non-space separated, case-insensitive, alphanumeric label that can be associated with a student for categorization. For example `bestFriend4Ever`, `colleague`, `Club` are valid tags, but `best friend`, `best-friend` are not valid tags. | +| **Autocomplete** | A feature that predicts and completes commands as you type. | +| **Command History** | A record of successfully executed commands that can be retrieved for reuse. | ### Abbreviations -| Abbreviation | Meaning | -|-------------|-------------------------------------------------------------------------| -| **ASCII** | American Standard Code for Information Interchange | -| **GUI** | Graphical User Interface | -| **CLI** | Command Line Interface | -| **TA** | Teaching Assistant | -| **CS** | Computer Science | -| **NUS** | National University of Singapore | -| **URL** | Uniform Resource Locator | -| **JSON** | JavaScript Object Notation | +| Abbreviation | Meaning | +|--------------|----------------------------------------------------| +| **ASCII** | American Standard Code for Information Interchange | +| **GUI** | Graphical User Interface | +| **CLI** | Command Line Interface | +| **TA** | Teaching Assistant | +| **CS** | Computer Science | +| **NUS** | National University of Singapore | +| **URL** | Uniform Resource Locator | +| **JSON** | JavaScript Object Notation | ### Recognised Prefixes for Attributes -| Prefix | Attribute | -|--------|-----------------------------| -| **n/** | Name of the student | -| **nn/** | NUSNet ID of the student | -| **p/** | Phone number of the student | -| **e/** | Email of the student | -| **m/** | Major of the student | -| **t/** | Tag of the student | +| Prefix | Attribute | +|---------|-----------------------------| +| **n/** | Name of the student | +| **nn/** | NUSNet ID of the student | +| **p/** | Phone number of the student | +| **e/** | Email of the student | +| **m/** | Major of the student | +| **t/** | Tag of the student | | **wk/** | Week number for attendance | This segment aims to make your TAPro experience as smooth as silk. With these notions and terms at your fingertips, you're well on your way to becoming a TAPro power user! @@ -164,7 +164,7 @@ A GUI similar to the below image should appear in a few seconds. Note how the ap * `addstu nn/E0952224 n/John Doe p/98765432 e/johnd@example.com m/Computer Science` : Adds a student named `John Doe` to the contact book. -* `delstu nn/NUSNET_ID` : Deletes the student with the specified `NUSNET_ID` from the contact book. +* `delstu nn/NUSNET` : Deletes the student with the specified `NUSNET` from the contact book. * `clear` : Deletes all students, and their contact and attendance information. @@ -323,23 +323,13 @@ Format: `addstu n/NAME nn/NUSNET [p/PHONE] [e/EMAIL] [m/MAJOR] [t/TAG]…​` -**Note:** NUSNet provided will be converted to uppercase automatically upon running the command. (e.g., `e0123456` will be converted to `E0123456`) - - - - -**Note:** Tags must be a single, non-space separated, alphanumeric word. For example `bestFriend4Ever`, `colleague`, `Club` are valid tags, but `best friend`, `best-friend` are not valid tags. - - - - -**Note:** The application will not wrap the text in the various fields. By [international standards](https://en.wikipedia.org/wiki/E.164), telephone numbers should not exceed 15 digits. And long names and email addresses are extremely rare, which falls outside of normal use cases. Lastly, most students will have no more than 2 majors. +**Note:** NUSNet ID is case-insensitive, and it will be converted to uppercase automatically upon running the command. (e.g., `e0123456` will be converted to `E0123456`) Examples: -* `addstu n/John Doe nn/e1234567 p/98765432 e/johnd@example.com m/Computer Science` -* `addstu n/Betsy Crowe nn/e0123456 t/friend e/betsycrowe@example.com m/Mathematics, Physics p/1234567 t/club` -* `addstu n/Betsy Crowe nn/e0123456` +* `addstu n/John Doe nn/E1234567 p/98765432 e/johnd@example.com m/Computer Science` +* `addstu n/Betsy Crowe nn/E0123456 t/friend e/betsycrowe@example.com m/Mathematics, Physics p/1234567 t/club` +* `addstu n/Betsy Crowe nn/E0123456` ---
@@ -361,7 +351,7 @@ If there are additional arguments behind `list` we will simply ignore them. Edits an existing person in the contact book. -Format: `edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [m/MAJOR] [nn/NUSNET_ID] [t/TAG]…​` +Format: `edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [m/MAJOR] [nn/NUSNET] [t/TAG]…​` * Edits the person at the specified `INDEX`. The index refers to the index number shown in the displayed person list. The index **must be a positive integer** 1, 2, 3, …​ * At least one of the optional fields must be provided. @@ -375,7 +365,7 @@ Examples: * `edit 2 n/Betsy Crower t/` Edits the name of the 2nd person to be `Betsy Crower` and clears all existing tags. -This command differs from most other commands that use the `NUSNET_ID` to identify a student. This command uses the index number shown in the displayed person list to identify the student to be edited. +This command differs from most other commands that use the `NUSNET` to identify a student. This command uses the index number shown in the displayed person list to identify the student to be edited. --- @@ -464,7 +454,7 @@ Format: `find KEYWORD [MORE_KEYWORDS]…​` Marks a student's attendance for a particular week. -Format: `mark nn/NUSNET_ID wk/WEEK_NUMBER` +Format: `mark nn/NUSNET wk/WEEK_NUMBER` Example: * `mark nn/E1234567 wk/3` @@ -476,7 +466,7 @@ Example: Unmarks a student's attendance for a particular week. -Format: `unmark nn/NUSNET_ID wk/WEEK_NUMBER` +Format: `unmark nn/NUSNET wk/WEEK_NUMBER` Example: * `unmark nn/E1234567 wk/3` @@ -489,7 +479,7 @@ Example: Deletes the specified student from the contact book. -Format: `delstu nn/NUSNET_ID` +Format: `delstu nn/NUSNET` * Deletes the student with the specified NUSNet ID from the contact book. @@ -497,7 +487,7 @@ Examples: * `delstu nn/E0957499` deletes the student with the NUSNet ID of `E0957499` in the contact book. Pro Tip: -* If you cannot remember your student's NUSNet ID, you could use `find Betsy` or `list` followed by `delstu nn/` to find and delete the student. +* If you cannot remember your student's NUSNet ID, you could use `find Betsy` or `list` followed by `delstu nn/` to find and delete the student. ---
@@ -833,6 +823,12 @@ Do also note that tags are alphanumeric and cannot contain spaces or special cha + + +**Q:** Long names, phone numbers, emails and majors are truncated in the UI. Why does TAPro not make these text wrap around?
+**A:** By [international standards](https://en.wikipedia.org/wiki/E.164), telephone numbers should not exceed 15 digits. And typical names and email addresses are rarely too long, which falls outside of normal use cases. Lastly, most students will have no more than 2 majors. So under any normal use case, the fields will not contain texts long enough to be truncated. Having a single line of text for each field also ensures the UI remains clean and uncluttered. + + ### Saving More Time @@ -876,7 +872,7 @@ the front of the command. 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. - + **2. If you have more than one copy of TAPro running** @@ -887,16 +883,16 @@ If you have more than one copy of TAPro running, the application may not functio ## Command summary -| Action | Format, Examples | -|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Add Student** | `addstu n/NAME p/PHONE_NUMBER e/EMAIL nn/NUSNET_ID m/MAJOR [t/TAG]…​`
e.g., `addstu n/James Ho p/22224444 e/jamesho@example.com nn/E1234567 m/Computer Science t/friend t/colleague` | -| **Clear** | `clear` | -| **Delete Student** | `delstu nn/NUSNET_ID`
e.g., `delstu nn/E0957499` | -| **Edit** | `edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [m/MAJOR] [t/TAG]…​`
e.g.,`edit 2 n/James Lee e/jameslee@example.com` | -| **Mark** | `mark nn/NUSNET_ID wk/WEEK_NUMBER`
e.g., `mark nn/E1234567 wk/3` | -| **Unmark** | `unmark nn/NUSNET_ID wk/WEEK_NUMBER`
e.g., `unmark nn/E1234567 wk/3` | -| **Find** | `find KEYWORD [MORE_KEYWORDS]…​`
e.g., `find James Jake` | -| **Set Course** | `setcrs COURSE_NAME` | -| **List** | `list` | -| **Help** | `help` | -| **Exit** | `exit` | +| Action | Format, Examples | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Add Student** | `addstu n/NAME p/PHONE_NUMBER e/EMAIL nn/NUSNET m/MAJOR [t/TAG]…​`
e.g., `addstu n/James Ho p/22224444 e/jamesho@example.com nn/E1234567 m/Computer Science t/friend t/colleague` | +| **Clear** | `clear` | +| **Delete Student** | `delstu nn/NUSNET`
e.g., `delstu nn/E0957499` | +| **Edit** | `edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [m/MAJOR] [t/TAG]…​`
e.g.,`edit 2 n/James Lee e/jameslee@example.com` | +| **Mark** | `mark nn/NUSNET wk/WEEK_NUMBER`
e.g., `mark nn/E1234567 wk/3` | +| **Unmark** | `unmark nn/NUSNET wk/WEEK_NUMBER`
e.g., `unmark nn/E1234567 wk/3` | +| **Find** | `find KEYWORD [MORE_KEYWORDS]…​`
e.g., `find James Jake` | +| **Set Course** | `setcrs COURSE_NAME` | +| **List** | `list` | +| **Help** | `help` | +| **Exit** | `exit` |