Merge e6e42ea into 956a358

docs/UserGuide.adoc

@@ -19,9 +19,17 @@ By: `Team W16-2`      Since: `Sept 2018`      Licence: `MIT`
 
 == Introduction
 
-SocialCare morphs the given AB4 application into a volunteer management system that allows Social Welfare Organisations to better manage their volunteers & events, and gain further statistical insights from the data. +
+Non-profit organizations rely on volunteer work to maintain parts of their operations. A volunteer management system is
+essential in helping to retain volunteers by ensuring that there is a large enough pool of volunteers who are motivated
+to support the various events. Therefore, it is critical that a organization is able
+to source the right person for the right activity.
 
-SocialCare is for organizations which *prefer to use a desktop app for managing their volunteers.* More importantly, SocialCare is *optimized for those who prefer to work with a Command Line Interface* (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, SocialCare can get your volunteer and event management tasks done faster than traditional GUI apps.
+SocialCare is an application that is designed to help your organization manage your volunteers effectively.
+You will be able to:
+
+* Manage volunteer information such as contact details.
+* Manage events for your organization.
+* Create volunteering records for your volunteers.
 
 Interested? Jump to <<Quick Start>> to get started.
 
@@ -35,17 +43,35 @@ To begin, follow the steps below:
 .  Check you have Java version `9` or later installed in your Computer.
 .  Download the latest `socialcare.jar` link:{repoURL}/releases[here].
 .  Copy the file to the folder you want to use as the home folder for SocialCare.
-.  Double-click the file to start the app. The GUI should appear in a few seconds.
+.  Double-click the file to start the app. The Graphic User Interface (GUI) should appear in a few seconds.
+
+.A labelled screenshot of the parts of the application
+image::UiLabelled.png[width="790"]
+
+The figure above shows the typical arrangement of the parts of the application. It is currently showing the screen that
+users will see upon startup.
+
+1. _Toolbar_: Provides quick access to exit the application or to open the user guide.
+
+2. _Panel_:  Displays volunteers or events, depending on which item you are managing.
+
+3. _Display Box_: Shows more information for the selected item from the panel.
+
+4. _Command Box_: Allows you to input commands for execution.
+
+5. _Command Result Box_: Displays status of executed commands.
 
-.GUI
-image::Ui.png[width="790"]
+6. _Status Bar_: Provides further information of application.
 
-The figure above is a sample display of the application.
 
 To ensure that everything is running, you can try entering commands into the command box and press kbd:[Enter] to execute them. +
 e.g. typing *`help`* and pressing kbd:[Enter] will open the help window.
 
+
 [NOTE]
+SocialCare allows you to manage both volunteers and events. The panel will update to show the relevant items. See
+<<command-switch>> for more details.
+
 You can refer to <<Features>> for details of each command.
 
 [[Features]]
@@ -86,7 +112,9 @@ Pressing the kbd:[&uarr;] and kbd:[&darr;] arrows will display the previous and
 ====
 
 Example(s):
-* `history`
+
+* `history` +
+The command result box will display the commands that you have entered in reverse chronological order.
 
 // tag::undoredo[]
 ==== Undoing previous command : `undo`
@@ -142,14 +170,14 @@ The `redo` command fails as there are no `undo` commands executed previously.
 
 ==== Clearing all entries : `clear`
 
-Clears all entries from the volunteers or events, depending on context. +
+Clears all data from the application.
 
 Format: `clear`
 
 Example(s):
 
 * `clear` +
-Resets the application to a clean state.
+Resets the application to a clean state. The panel is also updated to reflect the changes.
 
 [.clearfix]
 --
@@ -166,50 +194,50 @@ The figures above shows the before and after state of clearing the entries of th
 
 ==== Exiting the program : `exit`
 
-Exits the program. +
+Exits the application. +
 
 Format: `exit`
 
 Example(s):
 
 * `exit` +
-Exists from the program and return to the user's desktop.
+Exits from the application and return to the user's desktop.
 
 [[command-switch]]
-==== Switching context : `switch`
+==== Switching panels: `switch`
 
-Switches context to volunteers or events +
+Switches the panel to display to volunteers or events +
 
 Format: `switch -CONTEXT_ID`
 
 ****
-* The application will always start up in the 'volunteer' context.
-* Switch would switch the data view and allow the user to switch between two distinct entities: volunteers and events.
+* The application will always display the 'volunteer' panel upon startup .
+* This command allows you to switch the panel between two distinct entities: 'volunteers' and 'events'.
 * CONTEXT_ID for events is 'e'.
 * CONTEXT_ID for volunteers is 'v'.
 ****
 
 Example(s):
 
 * `switch -e` +
-Switch to the 'event' context when in 'volunteer' context.
+Updates the panel to display the list of events.
 
 [.clearfix]
 --
 [.left]
-.Before (Volunteer context)
+.Before: Panel displaying volunteers
 image::command_switch_before.png[switch bef, 450]
 [.left]
-.After (Event context)
+.After: Panel displaying events
 image::command_switch_after.png[switch aft, 450]
 --
 
-The figures above shows the 2 different contexts. +
-Application will start up in the 'volunteer' context and users can switch to the event context via the `switch` command.
+The figures above shows the 2 different panels. +
+Application will first display the 'volunteers' panel and you can change the panel to display 'events' via the `switch` command.
 
 === Volunteer Management
 
-==== Register new volunteer: `add`
+==== Registering new volunteer: `add`
 
 Adds a volunteer to the system when in the volunteers context +
 Format: `add n/NAME b/BIRTHDAY g/GENDER a/ADDRESS e/EMAIL p/PHONE_NUMBER [t/TAG]...`
@@ -286,7 +314,7 @@ image::VolunteerCert.png[width="600"]
 
 The following commands can only be accessed after switching to the 'event' context. (see <<command-switch>>)
 
-==== Add new event: `add`
+==== Adding new event: `add`
 
 Adds an event to the system when in the 'event' context. +
 
@@ -379,7 +407,7 @@ image::command_edit_event_before.png[Before add, 800]
 image::command_edit_event_after.png[After add, 800]
 --
 
-==== Deleting event details : `delete`
+==== Deleting event: `delete`
 
 Deletes details of an existing event in the system when in the 'event' context. +
 
@@ -406,13 +434,13 @@ This section contains commands related to managing a volunteering record.
 
 
 ****
-* The `manage` command can only be accessed after switching to the 'event' context. (see <<command-switch>>) +
+* The `manage` command can only be accessed after switching to the 'event' panel. (see <<command-switch>>) +
 * The other commands under this section can only be accessed after executing the `manage` command.
 ****
 
-==== View event's volunteer records: `manage`
+==== Viewing event's volunteer records: `manage`
 
-Switches to the 'manage' context and display volunteers at the left panel. +
+The panel updates to show the list of volunteers while the display area shows the volunteers currently registered for the selected event. +
 
 Format: `manage EVENT_INDEX`
 
@@ -421,69 +449,109 @@ Example(s):
 * `manage 1` +
 View the list of volunteers assigned to event at index 1.
 
-.Viewing of events
+.Panel of events
 image::command_switch_after.png[view events, 800]
 
-The figure above shows the 'event' context that the user has to be in before executing the `manage` command.
+The figure above shows the 'event' panel that you will see before executing the `manage` command.
+
+[NOTE]
+The number displayed next to the event name is the EVENT_INDEX that you have to enter.
 
-.Sample display
+.Managing the selected event
 image::command_manage_view.png[manage, 800]
 
-The figure above shows how the UI might look like after selecting to manage it. +
+The figure above shows the screen you will see after executing the `manage` command successfully.
+
+The following changes are observed:
 
-The left panel displays the list of volunteers while the right panel displays the event name and volunteers currently registered for the event.
+1. Panel displays the list of volunteers that you can assign to an event.
+2. Name of event being managed and total number of volunteers assigned to event shown in the upper portion of the display box.
+3. List of volunteers currently assigned to the event.
 
-==== Add volunteer to event: `add [coming in v1.3]`
+==== Adding volunteer to event: `add`
 
 Adds a volunteer to the event that is currently being managed. +
 
 Format: `add VOLUNTEER_INDEX [h/HOURS] [r/REMARKS]`
 
 ****
-* VOLUNTEER_INDEX comes from the list of all volunteers.
+* VOLUNTEER_INDEX comes from the list of all volunteers shown in the panel.
 * Default value for HOURS is '0'.
 * Default value for REMARKS is '-'.
 ****
 
-.Adding a record
-image::command_record_add.png[add record, 800]
+.The VOLUNTEER_INDEX
+image::command_record_add_volunteerIndex.png[volunteer index, 800]
 
-The circled numbers from the figure above indicate the VOLUNTEER_INDEX.
+The circled numbers from the figure above indicate the VOLUNTEER_INDEX that you have to enter.
 
 Example(s):
 
+.Before adding a volunteer
+image::command_record_add.png[add command, 800]
+
+The figure above shows how the screen looks like before executing the commands below.
+
 * `add 1` +
 Adds a volunteer at index 1 to the event with 0 hours. +
-* `add 1 r/Vegetarian` +
-Adds a volunteer at index 1 to the event with 0 hours with remarks of 'Vegetarian'.
-* `add 3 h/5` +
-Adds a volunteer at index 3 to the event with 5 hours.
+Expected display box is shown in the figure below.
 
-==== Update volunteer hours: `edit [coming in v1.3]`
+.Output of `add 1`
+image::command_record_add_after1.png[add command, 800]
 
-Updates a volunteering record for volunteer in the event that is currently being managed. +
 
-Format: `edit [-a] [VOLUNTEER_INDEX] h/HOURS [r/REMARKS]`
+* `add 1 r/Driver` +
+Adds a volunteer at index 1 to the event with 0 hours with remarks of 'Driver'.
+Expected display box is shown in the figure below.
+
+.Output of `add 1 r/Driver`
+image::command_record_add_after2.png[add command, 800]
+
+* `add 1 h/5` +
+Adds a volunteer at index 1 to the event with 5 hours. +
+Expected display box is shown in the figure below.
+
+.Output of `add 1 h/5`
+image::command_record_add_after3.png[add command, 800]
+
+* `add 1 h/5 r/Driver` +
+Adds a volunteer at index 1 to the event with 5 hours and remarks of 'Driver'. +
+Expected display box is shown in the figure below.
+
+.Output of `add 1 h/5 r/Driver`
+image::command_record_add_after4.png[add command, 800]
+
+
+==== Updating volunteer record: `edit`
+
+Updates a volunteer record in the event that is currently being managed. +
+
+Format: `edit VOLUNTEER_INDEX h/HOURS [r/REMARKS]`
 
 ****
 * VOLUNTEER_INDEX comes from the volunteers currently registered for the event.
-* VOLUNTEER_INDEX has to be specified if '-a' is not entered.
-* Entering just `r/` will save the remarks with the default value of '-'.
+* Just entering `r/` will save the remarks with the default value of '-'.
 ****
 
-.Editing a record
-image::command_record_edit.png[edit record, 800]
+.The VOLUNTEER_INDEX
+image::command_record_edit_volunteerIndex.png[volunteer index, 800]
 
-The highlighted column from the figure above indicate the VOLUNTEER_INDEX for each volunteer.
+The highlighted column from the figure above indicates the VOLUNTEER_INDEX that you have to enter.
 
 Example(s):
 
-* `edit -a h/5` +
-Updates amount of hours volunteered for all existing volunteers in the event to 5 hours.
-* `edit 3 h/5 r/Emcee` +
+* `edit 2 h/5 r/Emcee` +
 Updates amount of hours volunteered for volunteer at index 3 to 5 hours with remarks of 'Emcee'.
 
-==== Delete volunteer record from event: `delete [coming in v1.3]`
+.Before updating the volunteer record
+image::command_record_edit.png[edit command, 800]
+
+.Output of `edit 2 h/5 r/Emcee`
+image::command_record_edit_after.png[edit command, 800]
+
+The figures above show the display box before and after editing a record.
+
+==== Deleting volunteer record from event: `delete`
 
 Deletes the volunteer record from the event that is currently being managed. +
 
@@ -493,14 +561,24 @@ Format: `delete VOLUNTEER_INDEX`
 * VOLUNTEER_INDEX comes from the table view of existing volunteers.
 ****
 
-.Deleting a record
-image::command_record_edit.png[delete record, 800]
+.The VOLUNTEER_INDEX
+image::command_record_edit_volunteerIndex.png[delete record, 800]
+
+The highlighted column from the figure above indicates the VOLUNTEER_INDEX that you have to enter.
 
 
 Example(s):
 
 * `delete 1` +
-Deletes the volunteer record of the volunteer at index 1.
+Deletes the volunteer record at index 1.
+
+.Before deleting the volunteer record
+image::command_record_edit_after.png[delete command, 800]
+
+.Output of `delete 1`
+image::command_record_delete.png[delete command, 800]
+
+The figures above show the display box before and after deleting a record.
 
 === Miscellaneous