Deploy Scope Documentation

Each deploy: what changed.

Why document scope

Deploy scope docs are the contract between author and operators. They answer the "what changed at 14:32" question that on-call asks first during incidents; without the doc, on-call guesses and the incident extends.

• Undocumented deploys confuse responders. "What changed at 14:32?" question per incident; without the doc, on-call guesses and the investigation slows.
• Scope doc lists services, regions, impact, rollback. Four-section structure per deploy; standard shape across deploys supports fast scanning.
• Contract between author and operators. Documented expectation per deploy; lets operators trust the deploy and act on the change quickly.
• Named author per deploy. Responsible engineer per deploy catches "I do not know who deployed this" cases during incident response.

What goes in the doc

The contents are predictable: services touched, customer scope, database changes, rollback plan. The same four sections every time so on-call can scan rather than read.

• Services and components. Specific images, binaries, or config keys touched per deploy; concrete identifiers, not abstract descriptions.
• Regions and customer cohorts. Internal-only, percentage rollout, or all-customers scope per deploy; drives the blast-radius understanding for on-call.
• Database migrations. Forward, backward, downtime expectations per deploy with SQL provided; surprise migrations are how outages happen.
• Explicit rollback plan per deploy. Documented revert path per deploy catches "we do not know how to undo this" panics during failure response.

Automate scope capture

Manual capture decays. Auto-generate from the merge commit and CI artifacts, post to Slack, append to a searchable archive that supports later "what shipped when" queries.

• CI generates the doc. Auto-built scope doc per deploy from merge commit and CI artifacts; removes manual effort that decays.
• Auto-link to PRs, change logs, dashboards. Cross-linked context per deploy drives faster on-call investigation.
• Post to Slack. Channel-visible announcement per deploy supports cross-team awareness without requiring everyone to subscribe to a feed.
• Searchable archive per org. Indexed deploy-doc store per org supports later "what shipped on date X" queries during long-tail incident analysis.

Operational use

The doc earns its keep during incidents. On-call uses it for triage; post-incident review checks accuracy; doc quality becomes a leading indicator of process health.

• On-call triage. "Deploy 5 minutes ago changed X" reference per incident drives faster initial investigation.
• Post-incident review. Doc-vs-actual check per postmortem; was the deploy implicated, was the doc accurate.
• Doc quality as leading indicator. Doc-quality review per quarter; stale or absent docs signal process drift before it becomes an incident.
• Deploy-correlation evidence per incident. Doc-as-evidence per incident supports clear postmortem reasoning rather than hand-waved correlation claims.

How to roll out

Roll out with template, gate, audit. Each piece is small; together they install the discipline. Skip any one and the docs decay or never start.

• Start with a template. Deploy-doc template per org in CI tool or wiki; standard starting point.
• Required step before prod. Explicit gate per deploy; no promote without doc.
• Quarterly audit. 10-random-deploy review per quarter; coverage and quality both matter.
• Named documentation-quality owner per team. Responsible engineer per team catches "everyone-and-no-one" follow-up on the audit findings.