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:

  1. 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?
  2. 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

MR: gitlab-docs!3304 (merged)

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
  • 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
  • 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
  • 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