Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add valid data table and sample for editing data file in user guide #262

Merged
merged 9 commits into from
Apr 15, 2024
91 changes: 83 additions & 8 deletions docs/UserGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ Format: `edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [m/MODULE] [f/FACULTY] [v/VENUE

Examples:
* `edit 1 p/91234567 e/[email protected]` Edits the phone number and email address of the 1st person to be `91234567` and `[email protected]` respectively.
* `edit 3 m/GEA1000` Edits the module of the 3rd person to be `GEA1000`.
* `edit 3 m/GEA1000` Edits the module of the 3rd person to be `GEA1000`.
* `edit 2 n/Betsy Crower t/` Edits the name of the 2nd person to be `Betsy Crower` and clears all existing tags.
<br>**Before editing the second person:** <br>
![Before editing the second person](images/BeforeEditCommand.png)
Expand Down Expand Up @@ -376,7 +376,7 @@ Examples:

![Result of fav command](images/AfterFavCommand.png)

### Removes a person as favourite: `unfav`
### Removing a person as favourite: `unfav`

Removes the specified person from the staff book as favourite.

Expand All @@ -395,7 +395,7 @@ Examples:
* `sort p/` followed by `fav 1` removes the 1st person as favourite in the staff book in the results of the `sort` command, which should be the person with the smallest phone number.
* `find Betsy` followed by `unfav 1` removes the 1st person as favourite in the results of the `find` command.

### Refresh and clear all outdated meetings: `refresh`
### Refreshing and clearing all outdated meetings: `refresh`

<div markdown="block" class="alert alert-danger">:warning: **Caution:**
This may result in possible data loss. e.g. Meetings of a person may be deleted.
Expand Down Expand Up @@ -465,13 +465,87 @@ StaffConnect data are saved in the hard disk automatically after any command tha
StaffConnect data are saved automatically as a JSON file `[JAR file location]/data/staffconnect.json`. Advanced users are welcome to update data directly by editing that data file.

<div markdown="span" class="alert alert-warning">:exclamation: **Caution:**
If your changes to the data file makes its format invalid, StaffConnect 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>
If your changes to the data file makes its format invalid, StaffConnect 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 StaffConnect to behave in unexpected ways (e.g., if a value entered is outside of the acceptable range).
The application will not prompt the user if the format of the data file is incorrect, but instead provide the user with an empty staff book.
Therefore, edit the data file only if you are confident that you can update it correctly.
The application will not prompt the user if the format of the data file is incorrect, but instead provide the user with an empty staff book.<br>
**Therefore, edit the data file only if you are confident that you can update it correctly.**

</div>

#### Valid Data Values in `persons`

All attributes' restrictions except **Favourite** can be found in the [Attribute Summary](#attribute-summary) table.

Attribute | Data Field | Valid Data Values
----------|--------|-------------
Name | `name` | `Alice`, `Ben10`
Phone | `phone` | `123`, `98765432`
Email | `email` | `[email protected]`, `[email protected]`, `[email protected]`, `[email protected]`
Module | `module` | `gess1025`, `hsi1000`, `CS2103T`
Faculty | `faculty` | Refer to the [Valid Faculty Values](#valid-faculty-values) table.
Venue | `venue` | `COM4-02-33`, `LT21`, `Kent Ridge Vale, Tulip Street, #12-34`
Tag | `tags` | `professor`, `Number1TA`
Availabilitity | `availabilities` | `TUESDAY 12:00 13:00`, `WEDNESDAY 12:00 13:00`
Meeting | `meetings` | Refer to the [Valid Data Values in meetings](#valid-data-values-in-meetings) table.
Favourite | `favourite` | `Favourite` or `Not favourite`

#### Valid Data Values in `meetings`
tsulim marked this conversation as resolved.
Show resolved Hide resolved

Attribute | Meeting Data Fields | Valid Values
----------|--------|-------------
Meeting Description | `description` | `Meeting 1`, `Finals`
Meeting Start Time | `date` | `30/1/2024 12:12`, `2002-11-15 19:00`, `1-12-2022 9:00`, `2024/1/1 0000`

<div markdown="block" class="alert alert-primary">

**:exclamation: Important:**

* The value of `favourite` data field is case-sensitive.
* :heavy_check_mark: `Not favourite`
* :x: `not favourite`
* :x: `not FAVOURITE`
* There cannot be duplicates of
* `meeting` (exact same pair of `description` and `date`) in each `person`.
* `name` in the staff book.

</div>

#### Sample Data File Content

```json
{
"persons" : [ {
"name" : "Alex Yeoh",
"phone" : "87438807",
"email" : "[email protected]",
"module" : "CS1101S",
"faculty" : "School of Computing",
"venue" : "Blk 30 Geylang Street 29, #06-40",
"tags" : [ ],
"availabilities" : [ ],
"meetings" : [ ],
"favourite" : "Not favourite"
}, {
"name" : "John Smith",
"phone" : "99272758",
"email" : "[email protected]",
"module" : "CS2103S",
"faculty" : "School of Computing",
"venue" : "Blk 30 Lorong 3 Serangoon Gardens, #07-18",
"tags" : [ "friends", "tutor" ],
"availabilities" : [ "TUESDAY 12:00 13:00", "WEDNESDAY 12:00 13:00" ],
"meetings" : [ {
"description" : "test",
"date" : "12/12/2024 12:12"
}, {
"description" : "test2",
"date" : "10/10/2024 10:10"
} ],
"favourite" : "Favourite"
} ]
}
```

--------------------------------------------------------------------------------------------------------------------

## FAQ
Expand All @@ -489,6 +563,7 @@ Therefore, edit the data file only if you are confident that you can update it c
4. **When adding/editing name that already exists in the staff book**, if you try to do so, an error message will be prompted, as two persons are considered the same person as long as they have the same name. It is inplausible to has two persons with the same name but other different attributes.
5. **When adding/editing venues containing space with an attribute prefix**, If you try to add a venue such as `Room 12 t/r`, the application will add a person with a venue `Room 12` and a tag `r` instead of the intended venue `Room 12 t/r`. The venue is not intended to store venues that contains a space followed by an attribute prefix but users can consider omitting the space or replace with a hyphen such as `Room 12t/r` or `Room 12-t/r` as a workaround.
6. **When generating the default file and exiting via the `Exit` button**, If you try to generate the default JSON file `[JAR file location]/data/staffconnect.json` by running the JAR file, without manipulating any data and exiting via the `Exit` button, the JSON file would not be generated. You may consider using the `exit` command via the command line interface to generate the default JSON file instead.

--------------------------------------------------------------------------------------------------------------------

## Attribute summary
Expand All @@ -499,7 +574,7 @@ Name[^1] | n/ | Case-sensitive.<br>Only alphanumeric characters allowed. Spaces
Phone Number[^1] | p/ | Numeric digits only, no special characters, at least 3 digits long. | `123`, `88888888, 12345678`
Email[^1] | e/ | Valid email of the format `local-part@domain`.<br>1. `local-part` should only contain alphanumeric characters and the special characters `+_.-`<br>2. `local-part` may not start or end with any special characters.<br>3. `local-part` must be followed by exactly one `@` and then a `domain` name.<br>4. `domain` must be made up of at least 2 `domain` labels separated by periods.<br>5. Each `domain` name must be at least 2 alphanumeric characters long.<br>6. Each `domain` name must start and end with alphanumeric characters.<br>7. Each `domain` name can only consist of alphanumeric characters, separated by hyphens, if any. | `[email protected]`, `[email protected]`, `[email protected]`, `[email protected]`
Module[^1] | m/ | Case-insensitive.<br>Valid module consisting of 2-4 letters, followed by exactly 4 numeric digits, with a suffix that is at most 2 characters long. | `gess1025`, `hsi1000`, `cs2103t`
Faculty[^1] | f/ | Case-insensitive.<br>Restricted set of values (refer to [valid faculty values](#valid-faculty-values) below).<br>A valid faculty name and its variations (other names) all refer to the same faculty. | `soc`, `biz`, `School of Business`
Faculty[^1] | f/ | Case-insensitive.<br>Restricted set of values (refer to [Valid Faculty Values](#valid-faculty-values) below).<br>A valid faculty name and its variations (other names) all refer to the same faculty. | `soc`, `biz`, `School of Business`
Venue[^1] | v/ | Any characters allowed.<br>Cannot be empty. | `belobog avenue`, `COM4-02-33`, `LT21`, `Kent Ridge Vale, Tulip Street, #12-34`
Tag | t/ | Case-sensitive.<br>Only alphanumeric characters allowed.<br>Person can have any number of tags. | `tutor`, `professor`, `BestProf`, `Number1TA`
Availability | a/ | Valid format of `day start-time end-time`.<br>Person can have any number of availabilities.<br>1. `day` should be a valid day of week: `Monday`, `mon`, `Tuesday`, `tue`, `tues`, `Wednesday`, `wednes`, `wed`, `Thursday`, `thurs`, `thur`, `thu`, `Friday`, `fri`, `Saturday`, `satur`, `sat`, `Sunday`, `sun`.<br>2. `day` is case-insensitive.<br>3. `start-time` and `end-time` should be in the time format of `HH:mm` where `HH` is in 24 hours (00-23) and `mm` are valid minutes (00-59). | `mon 13:00 14:00`, `monday 13:00 14:00`, `tues 14:00 21:00`
Expand All @@ -508,7 +583,7 @@ Meeting Start Time | s/ | Valid date and time format.<br>1. Valid date formats:

[^1]: These are mandatory attributes when adding a person into the staff book, as these are important information for students to know when/where to consult their professors/TAs.

### Valid `Faculty` values
### Valid `Faculty` Values

Faculty | Other names
--------|------
Expand Down
Loading