Revamp incident management documentation section
Problem to solve
Now that the alerts management and incident management pages have been combined into a single topic (#231498 (closed)) it's time to rebuild them into a coherent section, likely multiple pages, that follow the concept → tasks → resources model.
Goal: get a working MVC in place in time for the %13.3 release so gitlab-com/www-gitlab-com!57773 (merged) has a viable new section of documentation to link to.
Proposed reorganization
Getting Started (NAV ITEM)
- Overview (Scope of Incident management)
- User Roles (what roles can and can't do)
Alerts (NAV ITEM)
-
Alert creation (REST endpoint, testing integrations, GitLab Alerts (management Prometheus), Externally-managed Prometheus, Opsgenie integration) -
Alert List (description of all columns and list view) -
Alert Details Page (Summary, Metrics, Logs, Runbook, system notes) -
Alert Actions (changing the status, assignment, create incident, GitLab Todos)
Alert Integrations (NAV ITEM)
-
HTTP Endpoint (Configuration, Adding custom mapping, testing) -
External Prometheus (Configuration, testing)
Alert Notifications (NAV ITEM)
-
Slack notifications -
Email notifications
Incidents (NAV ITEM)
-
Incident creation (Manual creation, auto-creation, PagerDuty Integration) -
Incident List (description of all columns and list view) -
Incident Details (Summary, metrics, logs, runbook, publish feature, related issues, merge requests, etc) -
Incident Actions (Assign, change severity, create to-do, embedding metrics, etc)
Status Page (NAV ITEM)
-
Set Up (Configuration) -
How to use
Plan - Split up by MR
-
Alerts MR -
Move content from alerts_details.md to alert.md (effectively condensing into a single page) - !43899 (merged) -
Reorganize alerts.md page into new format. -
Remove main nav items for Create and Manage alerts AND Alert Details and replace with Alerts. Link to alerts.md - gitlab-docs!1198 (merged) -
Redirect https://docs.gitlab.com/ee/operations/incident_management/alert_details.html
tohttps://docs.gitlab.com/ee/operations/incident_management/alert.html
-
-
Incidents MR: -
Change main nav item from Create and manage incidents to Incidents - gitlab-docs!1198 (merged) -
Reorganize Incidents page into new format
-
-
Overview MR -
Move content on configuring alerts to alerts.md
-
-
Notifications MR -
Create notifications.md - !43897 (merged) -
Move notifications content from overview to notification.md -
Add Alert notifications as a main nav item under incident management - gitlab-docs!1198 (merged)
-
-
Integrations MR: -
Change main nav item Generic alerts endpoint
toIntegrations
- gitlab-docs!1198 (merged) -
Change URL https://docs.gitlab.com/ee/operations/incident_management/generic_alerts.html
tohttps://docs.gitlab.com/ee/operations/incident_management/alert_integrations.html
- !44039 (merged) -
Reorganize page into new format
-
Other links/references
Related to #231498 (closed)
Edited by Sarah Waldner