Merge pull request #199 from chaaaaun/jiaen/update-dg

Update UG and DG
AY2324S2-CS2103T-T09-3 · Apr 15, 2024 · 1b5dfaa · 1b5dfaa
2 parents afb13e2 + 0044bfb
commit 1b5dfaa
Show file tree

Hide file tree

Showing 10 changed files with 83 additions and 25 deletions.
diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md
@@ -13,6 +13,7 @@ title: Developer Guide
 ## **Acknowledgements**
 
 * Elder Scrolls is based on the [AddressBook-Level3 project](https://nus-cs2103-ay2324s2.github.io/tp/) created by the [SE-EDU initiative](https://se-education.org).
+* The design of the Elder Scrolls user interface takes cues from Google's [Material Design system](https://m3.material.io/).
 
 --------------------------------------------------------------------------------------------------------------------
 
@@ -1108,7 +1109,28 @@ testers are expected to do more *exploratory* testing.
 
 
 ## **Appendix C: Effort**
-TODO
+
+### Difficulty Estimation
+
+Overall, the team believes that the features we have chosen to undertake are fairly complex, as they involve fundamental changes to the application state, as is the case with `undo` and `redo`. Additionally, the addition of `log` features and separation of person types meant that the existing relationships between entities inherited from AB3 had to be restructured significantly.
+
+The team also made significant changes to the UI, in an attempt to modernise the look and feel of the application. With meticulous reference to modern design systems, the team made significant changes to the styling of the application. These changes were challenging as they required a good understanding of JavaFX and the ability to work within the confines of the existing codebase.
+
+### Challenges Faced
+
+1. **Global ID vs Indexed ID**: We initially decided on using a global ID for each person, but later realised upon further exploration of the codebase that refactoring all instances of list indexing would be an outsized task. Thus, the team compromised by using global IDs for identifications, but still using list indices for client-facing commands.
+2. **Adding Logs**: The team faced challenges in adding logs to the application, as it required a significant restructuring of the existing codebase. Given that logs were an entirely new set of entities to be stored in the application, where AB3 had only a single entity, we quickly realised that the existing structure of the `model` was not sufficient to handle the new requirements. This led to a significant amount of refactoring and restructuring of the `Model` and `Storage` classes.
+3. **Relationships between entities**: Given that the new features included two different classes of `Person` as well as a `Log` class associated with both, the team spent a significant amount of time planning and testing the correctness of the relations between these entities. Through defensive programming and good test coverage, we were able to ensure that all user operations modifying these relationships were correctly reflected in the application state.
+
+### Effort Required
+
+Overall, over the thousands of lines of code changed, the team estimates that a few dozen man-hours were spent on the project. The team met regularly to discuss the project, and each member contributed significantly to the project through an even distribution of work over the main areas: adding commands, restructuring logic and backend, UI. The team also spent a significant amount of time on testing, as the new features added to the application were complex and required a significant amount of additional test code to ensure that they worked as expected.
+
+As a result, we were able to deliver on planned features while increasing our code coverage over the inherited project.
+
+### Achievements
+
+A robust and extensible application was delivered, with a significant amount of new features added to the application. The team was able to deliver on planned features, and the performance of new features, such as `log` operations, were significantly improved over old features of the inherited project.
 
 ## **Appendix D: Planned Enhancements**
 

diff --git a/docs/UserGuide.md b/docs/UserGuide.md
@@ -13,7 +13,6 @@ title: User Guide
 
 ## **About this User Guide**
 
-
 Welcome to the user guide for Elder Scrolls! Whether you're new or experienced, this guide has everything you need to make the most of Elder Scrolls:
 
 * [Quick Start](#1-quick-start): Get started with Elder Scrolls quickly and easily.
@@ -54,40 +53,83 @@ Once you've completed the setup, you're ready to launch Elder Scrolls! Follow th
 
 A GUI similar to the one below should appear in a few seconds. If this is your first time launching Elder Scrolls, the application should contain some sample data to get you started!
 
-<div style="text-align:center;">
-  <img src="images/Ui.png" alt="Ui" width="400">
-  <p></p>
+<div style="text-align:center; margin-bottom: 1.5em">
+  <img src="images/Ui.png" alt="Ui" width="600">
+  <i>The starting user interface with sample data</i>
 </div>
 
 After this, you're all set to begin using Elder Scrolls! Let's make managing volunteers and befriendees a breeze.
 
-Here are some commands to get you started:
+Lets walk you through some important commands to get you started:
+
+1. The most integral function of Elder Scrolls is to help you to keep track of the people in your volunteering organisation. Naturally, there is a way to add new volunteers and befriendees to the system. Let's try adding a new befriendee, John Doe, to the system using the `add` command.
+
+    ```
+    add n/John Doe p/98765432 e/[email protected] a/John Street, Block 123, #01-01 r/befriendee
+    ```
+   
+    ![result for 'add John Doe'](images/addJohnResult.png)
+
+    Scroll down the befriendee list, and you should see John's card at the bottom of the list.
+
+2. Now that he's officially joined, John needs a friend! Let's have one of our volunteers, Bernice, take care of him. From the list, you can see that Bernice has been hard at work befriending Irfan, but sadly, we'll need to reassign her. Let's unpair Bernice and Irfan using the `unpair` command, since Irfan sits at the 2nd index in the befriendee list.
+
+    ```
+    unpair 2 1
+    ```
+   
+    ![result for 'unpair 2 1'](images/unpairResult.png)
+    
+    Both lists should reset to their original state, and looking at Bernice and Irfan's cards, they should no longer be paired.
 
-   * `find David`: Finds all contacts with names containing `David`.
+3. Now we are ready to pair Bernice with John. But wait, John's card is too far down the list, and we're a little lazy to scroll down to find his index. No problem, one of the most powerful features of Elder Scrolls is the `find` command. This command allows you to search for contacts based on various criteria, such as name, role, pairing status, and tags. Now, let's try to bring John to the top of our list using the `find` command.
 
-   * `list` : Lists all befriendee and volunteer contacts.
+    ```
+    find r/befriendee John
+    ```
 
-   * ```add n/John Doe p/98765432 e/[email protected] a/John street, block 123, #01-01 r/volunteer``` : Adds a volunteer named `John Doe` to the Elder Scrolls.
+    ![result for 'find John'](images/findJohnResult.png)
 
-   * `delete 4 r/volunteer ` : Deletes the 4th contact shown in the current list.
+    Here, we've specified the `r/befriendee` filter, which ensures we only search in the befriendee list, leaving the volunteer list untouched.
 
-   * `clear` : Deletes all contacts.
+4. Now that we've found John, let's pair him with Bernice. Bernice sits at the 2nd index in the volunteer list, so we can pair them using the `pair` command.
 
-   * `exit` : Exits the app.
+    ```
+    pair 1 2
+    ```
+   
+    ![result for 'pair 1 2'](images/pairResult.png)
 
-   * Refer to the [Features](#3-features) below for details of each command.
+5. Finally, let's add an entry in `Logs` to record the first meeting between Bernice and John. We can `find` John again, then use the `logadd` command to do this.
 
-Great! Now that you're familiar with the fundamental commands and have successfully launched Elder Scrolls, let's delve deeper into its intricacies and explore its advanced functionalities.
+    ```
+    find r/befriendee John
+    ```
+    ```
+    logadd 1 2 t/First Meeting s/2024-04-10 d/1 r/Introduction
+    ```
+
+    ![result for 'logadd'](images/logaddResult.png)
+
+    You should see the log card appear at the bottom of the `Logs` list, with the details you supplied.
+
+6. This summarizes the basic workflow of Elder Scrolls. Feel free to remove the sample data and start fresh by using the `clear` command and get started with your own data!
+
+    ```
+    clear
+    ```
+
+    The lists should now be empty, ready for you to start managing your own volunteers and befriendees!
+
+7. You can refer to the [Features](#3-features) below for detailed descriptions of all the commands available in Elder Scrolls.
 
 --------------------------------------------------------------------------------------------------------------------
 
 ## **2. User Interface**
 
 <div style="text-align:center;">
   <img src="images/UserInterface.jpg" alt="Ui" width="700">
-</div>
-<div align="center">
-  <text><u> Image: User interface Layout Breakdown of Elder Scrolls </u></text>
+  <i>User interface Layout Breakdown of Elder Scrolls </i>
 </div>
 
 ### 2.1 Toolbar

diff --git a/docs/images/Ui.png b/docs/images/Ui.png
diff --git a/docs/images/addJohnResult.png b/docs/images/addJohnResult.png
diff --git a/docs/images/findBerniceResult.png b/docs/images/findBerniceResult.png
diff --git a/docs/images/findJohnResult.png b/docs/images/findJohnResult.png
diff --git a/docs/images/logaddResult.png b/docs/images/logaddResult.png
diff --git a/docs/images/pairResult.png b/docs/images/pairResult.png
diff --git a/docs/images/unpairResult.png b/docs/images/unpairResult.png
diff --git a/docs/index.md b/docs/index.md
@@ -6,16 +6,10 @@ title: Elder Scrolls
 [![CI Status](https://github.com/AY2324S2-CS2103T-T09-3/tp/actions/workflows/gradle.yml/badge.svg)](https://github.com/AY2324S2-CS2103T-T09-3/tp/actions)
 [![codecov](https://codecov.io/gh/AY2324S2-CS2103T-T09-3/tp/graph/badge.svg?token=7N2EZAM58I)](https://codecov.io/gh/AY2324S2-CS2103T-T09-3/tp)
 
-[//]: # (![Ui]&#40;images/Ui.png&#41;{: width="600"})
-
-<div style="text-align:center;">
+<div style="text-align:center; margin-bottom: 1.5em">
   <img src="images/Ui.png" alt="Ui" width="600">
+  <i>Elder Scrolls</i>
 </div>
-<div align="center">
-  <text> Elder Scrolls </text>
-  <p></p>
-</div>
-
 
 **Elder Scrolls** is a ___Volunteer Management System (VMS)___ designed to streamline the coordination of volunteers and befriendees, with a particular focus on elderly befriending programs. Elder Scrolls combines the _speed of CLI interaction_ with the benefits of a _Graphical User Interface (GUI)_. Whether you prefer the agility of typing or the convenience of visual interaction, Elder Scrolls ensures that your volunteer management tasks are completed swiftly and seamlessly.