Updates documentation

docs/SUMMARY.md

@@ -2,34 +2,30 @@
 
 - [About](README.md)
 - [Installation](installation.md)
-- [User Guide](user-guide/README.md)
-  - [Incident Participant](user-guide/incident-participant.md)
-  - [Incident Commander](user-guide/incident-commander.md)
-  - [Incidents](user-guide/incident.md)
-  - [Tasks](user-guide/tasks.md)
-  - [Feedback](user-guide/feedback.md)
-  - [Data](user-guide/data.md)
-  - [Dashboards](user-guide/dashboard.md)
 - [Administration Guide](user-guide/administration/README.md)
   - [Project](admin-guide/administration/project.md)
+  - [Plugins](admin-guide/administration/incident/plugins/README.md)
+    - [Configuring G Suite](admin-guide/administration/incident/plugins/configuring-g-suite.md)
+    - [Configuring Jira](admin-guide/administration/incident/plugins/configuring-jira.md)
+    - [Configuring Opsgenie](admin-guide/administration/incident/plugins/configuring-opsgenie.md)
+    - [Configuring PagerDuty](admin-guide/administration/incident/plugins/configuring-pagerduty.md)
+    - [Configuring Slack](admin-guide/administration/incident/plugins/configuring-slack.md)
+    - [Configuring Zoom](admin-guide/administration/incident/plugins/configuring-zoom.md)
+  - [Templates](admin-guide/administration/templates.md)
+  - [Contacts](admin-guide/administration/contact/README.md)
+    - [Services](admin-guide/administration/contact/service.md)
+    - [Individuals](admin-guide/administration/contact/individual.md)
+    - [Teams](admin-guide/administration/contact/team.md)
+  - [Case](admin-guide/administration/case/README.md)
+    - [Case Types](admin-guide/administration/case/case-type.md)
+    - [Case Severities](admin-guide/administration/case/case-severity.md)
+    - [Case Priorities](admin-guide/administration/case/case-priority.md)
   - [Incident](admin-guide/administration/incident/README.md)
-    - [Incident Prioritites](admin-guide/administration/incident/incident-priority.md)
     - [Incident Types](admin-guide/administration/incident/incident-type.md)
+    - [Incident Prioritites](admin-guide/administration/incident/incident-priority.md)
     - [Incident Cost Types](admin-guide/administration/incident/incident-cost-type.md)
-    - [Templates](admin-guide/administration/incident/templates.md)
     - [Workflows](admin-guide/administration/incident/workflow.md)
     - [Notifications](admin-guide/administration/incident/notification.md)
-    - [Plugins](admin-guide/administration/incident/plugins/README.md)
-      - [Configuring G Suite](admin-guide/administration/incident/plugins/configuring-g-suite.md)
-      - [Configuring Jira](admin-guide/administration/incident/plugins/configuring-jira.md)
-      - [Configuring Opsgenie](admin-guide/administration/incident/plugins/configuring-opsgenie.md)
-      - [Configuring PagerDuty](admin-guide/administration/incident/plugins/configuring-pagerduty.md)
-      - [Configuring Slack](admin-guide/administration/incident/plugins/configuring-slack.md)
-      - [Configuring Zoom](admin-guide/administration/incident/plugins/configuring-zoom.md)
-  - [Contacts](admin-guide/administration/contact/README.md)
-    - [Services](admin-guide/administration/contact/service.md)
-    - [Individuals](admin-guide/administration/contact/individual.md)
-    - [Teams](admin-guide/administration/contact/team.md)
   - [Knowledge](admin-guide/administration/knowledge/README.md)
     - [Tag Types](admin-guide/administration/knowledge/tag-type.md)
     - [Tags](admin-guide/administration/knowledge/tag.md)
@@ -46,6 +42,14 @@
   - [API](admin-guide/administration/api.md)
   - [Server](admin-guide/administration/server.md)
   - [User](admin-guide/administration/user.md)
+- [User Guide](user-guide/README.md)
+  - [Incident Participant](user-guide/incident-participant.md)
+  - [Incident Commander](user-guide/incident-commander.md)
+  - [Incidents](user-guide/incident.md)
+  - [Tasks](user-guide/tasks.md)
+  - [Feedback](user-guide/feedback.md)
+  - [Data](user-guide/data.md)
+  - [Dashboards](user-guide/dashboard.md)
 - [Contributing](contributing/README.md)
   - [Environment](contributing/environment.md)
   - [Core](contributing/core.md)

docs/admin-guide/administration/case/README.md

@@ -0,0 +1,5 @@
+---
+description: View and manage all cases.
+---
+
+While Dispatch holds some strong opinions about _how_ to run cases. It does allow for quite a lot of flexibility. Below you will find several different areas that allow you to make the case experience fit your organization.

docs/admin-guide/administration/case/case-priority.md

@@ -0,0 +1,17 @@
+## Case Priority
+
+In addition to case types, Dispatch allows you to specify the case's priority.
+
+![](../../../.gitbook/assets/admin-ui-case-priorities.png)
+
+**Name:** The name of the case priority presented to the user.
+
+**Description:** The description of the case priority presented to the user.
+
+**View Order:** The order in which the priority will be listed in menus and dropdowns.
+
+**Color:** The color used for the case priority in the UI.
+
+**Default Case Priority:** If the reporter of a case does not provide a priority, a default will be used. Enable the setting to make this case priority the default.
+
+**Enabled:** Whether this case priority is enabled or not.

docs/admin-guide/administration/case/case-severity.md

@@ -0,0 +1,17 @@
+## Case Severity
+
+In addition to case types, Dispatch allows you to specify the case's severity.
+
+![](../../../.gitbook/assets/admin-ui-case-severities.png)
+
+**Name:** The name of the case severity presented to the user.
+
+**Description:** The description of the case severity presented to the user.
+
+**View Order:** The order in which the severity will be listed in menus and dropdowns.
+
+**Color:** The color used for the case severity in the UI.
+
+**Default Case Severity:** If the reporter of a case does not provide a severity, a default will be used. Enable the setting to make this case severity the default.
+
+**Enabled:** Whether this case severity is enabled or not.

docs/admin-guide/administration/case/case-type.md

@@ -0,0 +1,25 @@
+## Case Types
+
+Dispatch allows you to categorize your cases by defining case types and to map them to various Dispatch resources (e.g. templates, oncall services, and incident types).
+
+![](../../../.gitbook/assets/admin-ui-case-types.png)
+
+**Name:** The name of the case type presented to the user.
+
+**Description:** The description of the case type presented to the user.
+
+**Visibility:** Allows you to specify how visible a case of this type will be. Note: this option is currently not being leveraged.
+
+**Case Template:** Allows you to create a new or map an existing case document template to the case type.
+
+**Oncall Service:** Allows you to map an existing oncall service that will be used to determing the owner of the case.
+
+**Incident Type:** The type of incident that will be created and linked to the case if a case of this type is moved to the Escalated status.
+
+**Exclude From Metrics:** Enable this setting to exclude all cases of this type from metrics (e.g., test cases).
+
+**Default Case Type:** If the creator of a case does not provide a case type, a default case type is used. Enable this setting to make this case type the default.
+
+**Enabled:** Whether the case type is enabled or not.
+
+**Plugin Metadata:** Allows you to define and pass metadata key-value pairs to plugins. For example, create issues in different Jira projects based on the case type.

docs/admin-guide/administration/incident/README.md

@@ -2,4 +2,4 @@
 description: View and manage all incidents.
 ---
 
-While Dispatch holds some strong opinions about _how_ to run incidents. It does allow for quite a lot of flexibility. Below you will find several different areas that allow you to make the incident experiance fit your organization.
+While Dispatch holds some strong opinions about _how_ to run incidents. It does allow for quite a lot of flexibility. Below you will find several different areas that allow you to make the incident experience fit your organization.

docs/admin-guide/administration/incident/incident-priority.md

@@ -6,14 +6,18 @@ In addition to incident types, Dispatch allows you to specify the incident's _pr
 
 **Name:** The name of the incident priority presented to the user.
 
-**Description:** The incident priority description presented to the user when reporting.
+**Description:** The description of the incident priority presented to the user when reporting.
 
-**View Order:** The ranked order which the priority will be listed in menus and dropdowns.
+**View Order:** The order in which the priority will be listed in menus and dropdowns.
 
 **Tactical Report Reminder:** Number of hours between reminders.
 
 **Executive Report Reminder:** Number of hours between reminders.
 
+**Page Commander:** Ensures that the incident commander is paged for all incidents with this priority (if configured paging service and plugin allows).
+
+**Color:** The color used for the incident priority in the UI.
+
 **Default Incident Priority:** If the reporter of an incident does not provide an incident priority, a default will be used. Enable the setting to make this incident priority the default.
 
-**Page Commander:** Ensures that the incident commander is paged for all incidents with this priority (if configured paging service and plugin allows).
+**Enabled:** Whether this incident priority is enabled or not.

docs/admin-guide/administration/incident/incident-type.md

@@ -1,6 +1,6 @@
 ## Incident Types
 
-Dispatch allows you to define incident types. Incident types bucket or categorize your incidents and map various other Dispatch resources (e.g., services and individuals) to these types.
+Dispatch allows you to categorize your incidents by defining incidents types and to map them to various Dispatch resources (e.g. templates).
 
 ![](../../../.gitbook/assets/admin-ui-incident-types.png)
 

docs/admin-guide/administration/project.md

@@ -4,18 +4,28 @@ description: Overview of the Dispatch projects.
 
 # Projects
 
-Every incident within Dispatch is tied to a project. The project and its resources/configuration determine how the incident is run. This allows multiple teams to use Dispatch in different ways.
+Every case or incident within Dispatch is tied to a project. The project configuration determines how cases or incidents are created and managed. This allows multiple teams to use Dispatch in different ways.
 
-From having their own incident types and priorities to providing the team with a view of their incident metrics. Projects drive this scoping of incidents.
+From having their own case or incident types and priorities to providing the team with a view of their metrics.
 
 ### When should I create a new project vs using an existing one?
 
-Generally, you would create a new project when the teams involved have very little overlap when handling incidents.
+Generally, you would create a new project when the teams involved have very little overlap when handling cases or incidents.
 
-For example, you might create a `security` project for the handling of all security related incidents and a `reliability` project for all outage related incidents.
+For example, you might create a `security` project for the handling of all security-related cases or incidents and a `reliability` project for all outage-related incidents.
 
 ![](../../.gitbook/assets/admin-ui-project.png)
 
-**Name:** The name you wish to give your project.
+**Name:** A name for your project.
 
-**Description:** A brief description of the project.
+**Description:** A description for your project.
+
+**Color:** A color for your project, so you can visually differentiate it from other projects. 
+
+**Annual Employee Cost:** An annual average cost per employee.
+
+**Business Year Hours:** Number of working hours in a year. Used to calculate hourly rate.
+
+**Owner Email:** The email account of the project owner.
+
+**Owner Conversation:** The conversation of the project owner (e.g. Slack channel).

docs/admin-guide/administration/incident/templates.md → docs/admin-guide/administration/templates.md

@@ -1,43 +1,61 @@
 ## Templates
 
-Templates are special types of documents that are used by Dispatch to create incident specific documentation. These templates are copied and filled out to the best of Dispatch's abilities.
+Templates are used by Dispatch to create case or incident specific documentation. These templates are copied and filled out to the best of Dispatch's abilities. After their creation, they are normal documents that are associated to your case or incident and can be used for collaborating and capturing facts and findings.
 
-After creation they are normal documents that are associated to your incident which can be freely edited.
-
-There are four main types of templates that Dispatch supports:
+There are several types of templates that Dispatch supports:
 
+- Case
 - Incident
 - Executive
 - Review
 - Tracking
 
-Each type of template is fairly straightforward mapping directly to the incident response process. For example:
+![](../../../.gitbook/assets/admin-ui-create-edit-template.png)
 
-### Incident
+**Name:** Name of the template.
 
-A copy of this template is created for each new incident on incident creation. It contains the current state of the incident and is used by incident participants to share knowledge about the incident.
+**Description:** Description of the template.
 
-- [Example Incident Document](https://docs.google.com/document/d/1fv--CrGpWJJ4nyPR0N0hq4JchHJPuqsXN4azE9CGQiE)
+**Weblink:** The weblink to the template.
 
-### Executive
+**External Id:** External identifier for the document template. Used for API integration (e.g. Google doc file id). Typically, the unique id in the weblink.
 
-Often during an incident an executive report needs to be drafted that provides a high-level overview of the incident and the current actions that are being carried out. A copy of this template will be created, filled, and stored in the incident storage every time a new executive report is drafted.
+Enabling evergreen for a template instructs Dispatch to send an email reminder to the template owner informing them that they should review the template to ensure that the template is up to date.
 
-- [Example Executive Report](https://docs.google.com/document/d/1dab6k14p5ageo5B_d1YlB_zS9hMGHDMXy9RUbIZous4)
+**Evergreen Owner:** The email address representing the owner of this document template.
 
-### Review
+**Evergreen Reminder Interval:** Number of days that should elapse between reminders sent to the document template owner.
 
-A copy of this template is automatically created when an incident is marked as stable. It is used by the incident commander and participants for reconciling any incident learnings, discussions, or post-incident tasks.
+### Case Template
 
-- [Example Incident Review Document](https://docs.google.com/document/d/1MkCTyheZRtKzMxOBhLgh3PrvarERA9Bwo0joM7D9tmg)
+A copy of this template is created for each new case on case creation. It contains the current state of the case and is used by the case owner/ assignee to capture facts and findings.
 
-### Tracking
+- [Example Case Document](https://docs.google.com/document/d/1g1cl9liXG8US0eBnrZYRaeWa7Ek_hoZJ5PPadas44vI)
 
-Some incidents require the tracking of multiple assets, this template is a simple spreadsheet that allows incident participants to collaborate on tabular data.
+#### Template Variables
 
-- [Example Incident Tracking Sheet](https://docs.google.com/spreadsheets/d/1Odk4KlL7uMF_yd7OvTOCaPWmtTA_WzFBIA4lMeU5cGY)
+The following is a list of available variables that Dispatch will attempt to resolve on document creation. Note: we do not currently re-resolve these.
+
+NOTE: All variables must be enclosed in a `{{}}`
+
+- `case_name` - The case's name
+- `case_title` - The cases's title
+- `case_description` - The case's description
+- `case_resolution` - The case's resolution
+- `case_owner` - The case's owner
+- `case_type` - The case's type
+- `case_severity` - The case's severity
+- `case_priority` - The case's priority
+- `case_status` - The case's status
+- `case_storage_weblink` - Link to the storage resource
+
+### Incident Template
 
-### Template Variables
+A copy of this template is created for each new incident on incident creation. It contains the current state of the incident and is used by incident participants to share knowledge about the incident.
+
+- [Example Incident Document](https://docs.google.com/document/d/1fv--CrGpWJJ4nyPR0N0hq4JchHJPuqsXN4azE9CGQiE)
+
+#### Template Variables
 
 The following is a list of available variables that Dispatch will attempt to resolve on document creation. Note: we do not currently re-resolve these.
 
@@ -48,31 +66,39 @@ NOTE: All variables must be enclosed in a `{{}}`
 - `description` - The incident's description
 - `resolution` - The incident's resolution
 - `commander_fullname` - The current commander's name
-- `type` - The incident's type name
-- `prioritity` - The incident's priority name
+- `type` - The incident's type
+- `prioritity` - The incident's priority
 - `status` - The incident's status
 - `conversation_weblink` - Link to the conversation resource (if any)
 - `conference_weblink` - Link to the conference resource (if any)
 - `storage_weblink` - Link to the storage resource (if any)
 - `document_weblink` - Link to the incident document (if any)
 - `ticket_weblink` - Link to the incident ticket (if any)
 
-### Association
+### Executive Template
 
-Each of these templates can be associated on a per-incident type basis. This allows our templates to closely match a given incident type and provide additional context direction for those incident types.
+Often during an incident an executive report needs to be drafted that provides a high-level overview of the incident and the current actions that are being carried out. A copy of this template will be created, filled, and stored in the incident storage every time a new executive report is drafted.
 
-Additionally, templates can be associated with multiple incident types, if for example, you only want to use one template.
+- [Example Executive Report](https://docs.google.com/document/d/1dab6k14p5ageo5B_d1YlB_zS9hMGHDMXy9RUbIZous4)
 
-![](../../../.gitbook/assets/admin-ui-create-edit-template.png)
+### Review Template
 
-**Name:** Name of the template.
+A copy of this template is automatically created when an incident is marked as stable. It is used by the incident commander and participants for reconciling any incident learnings, discussions, or post-incident tasks.
 
-**Description:** Short description of the template.
+- [Example Incident Review Document](https://docs.google.com/document/d/1MkCTyheZRtKzMxOBhLgh3PrvarERA9Bwo0joM7D9tmg)
 
-**Weblink:** The weblink to the template.
+### Tracking Template
 
-**ID:** The template's external ID used to fetch the document.
+Some incidents require the tracking of multiple assets, this template is a simple spreadsheet that allows incident participants to collaborate on tabular data.
 
-### Evergreen
+- [Example Incident Tracking Sheet](https://docs.google.com/spreadsheets/d/1Odk4KlL7uMF_yd7OvTOCaPWmtTA_WzFBIA4lMeU5cGY)
 
-Enabling evergreen for a template instructs Dispatch to send an email reminder to the template owner informing them that they should review the template to ensure that the template is up to date.
+### Template Association
+
+Case and incident templates can be associated to their corresponding types. This allows our templates to closely match a given case or incident type and provide additional context and direction for those given types.
+
+Additionally, templates can be associated with multiple case or incident types, if for example, you only want to use one template.
+
+![](../../../.gitbook/assets/admin-ui-associate-case-template.png)
+
+![](../../../.gitbook/assets/admin-ui-associate-incident-template.png)