Deploy Scope Documentation

Each deploy: what changed.

Why document scope

Deploys without documented scope confuse responders during incidents. "What changed at 14:32?" is the question that needs an answer.

Scope doc lists: services touched, regions, customer impact, rollback plan.

Documentation is the contract between author and operators.

What goes in the doc

Services and components affected. Specific images, binaries, or config keys.

Regions and customer cohorts. Internal-only, percentage rollout, all customers.

Database migrations: forward, backward, downtime expectation. SQL provided.

Automate scope capture

CI generates a deploy doc from the merge commit and CI artifacts.

Auto-link to PRs, change logs, dashboards.

Post the doc to Slack and append to the deployment record.

Operational use

On-call uses the doc during incident triage. "Deploy 5 minutes ago changed checkout-api; check there first."

Post-incident review references the doc. Was the deploy implicated. Was the doc accurate.

Stale or absent docs are leading indicators of process drift.

How to roll out

Start with a deploy template in your CI tool or wiki.

Make the doc a required step before promoting to prod.

Audit quarterly: pick 10 random deploys, check the docs. Coverage and quality both matter.