Restructure incident management docs around slack features
Problem
Docs for how to use Slack with our incident management features are currently very minimal (two sentences!) and presented on the two, separate pages - Incident docs page and Paging and notifications.
We should figure out:
- Where do we want the Slack docs to go? Should we have create a new page, specifically to document the Slack workflow for incident management? Should we consolidate the Slack docs, so they're only in one place?
- How to structure the docs so that, as we add new features to the Slack integration for incident management, we can add them in a way that makes sense.
Proposal
Restructure docs pages
Re-arrange the existing docs pages so that similar content is together. Also introduce a new page for Slack. That would look like this:
Incident Management
- Alerts
- Integrations
- Incidents
- On-call schedules
- Escalation Policies
- Paging and notifications
- Slack
- Status page
New Slack page structure
MR: !104104 (merged)
- Incident management in Slack
- description of why to use GitLab Slack app for incident management
- small diagram of user/data flow
- Setup and configuration
- Enabling incident slash commands in Slack
- permissions & link to Slack app page
- Enabling incident notifications from GitLab to Slack
- permissions & instructions for incident-specific notifications
- link to instructions for setting up Slack notifications for all issues
- Enabling incident slash commands in Slack
- Managing a GitLab incident from Slack
- Declare an incident
- permissions & instructions
- Utilize an incident template
- link to incident template docs
- link to incident-specific quick actions reference below
- Link an existing Slack channel to an incident
- link to resource links docs
- Create a new Slack channel for a new incident [To be added once the feature exists]
- permissions & instructions
- Add a comment
- permissions & instructions
- link to incident-specific quick actions reference below
- Add a timeline event
- permissions & instructions
- link to timeline events docs
- Close an incident
- permissions & instructions
- link to incident closing docs
- Declare an incident
- Sending GitLab incident notifications to Slack
- When an incident is declared
- link to configuration section above
- description of information included in the notification
- When a timeline event is added [To be added once the feature exists]
- link to configuration section above
- description of information included in the notification
- When an incident is declared
- Incident-specific commands cheat sheet
- link to docs on referencing GitLab usernames from slack
- Slack slash commands
- link to slash command reference page
- table of incident-specific slash commands
- GitLab quick actions
- link to quick action page
- table of incident-specific quick actions
- Troubleshooting
- No projects in the incident creation project dropdown
- Slash commands not listed in shortcut menu
Existing Slack pages
When we have the new Slack page in place, we can add a link to it from the smaller, summary pages on the Incident and Paging and notifications pages.
Edited by Marcin Sedlak-Jakubowski