# Operations Deployment Guide > Generate a professional Operations & Deployment Guide as a formatted Word (.docx) file — environments, infrastructure, deployment architecture, CI/CD pipeline, deployment/rollback procedures, configuration and secrets management, backups, and disaster recovery. Use this whenever someone asks for a "deployment guide," "infra runbook," "release process document," or wants to document how a system is deployed and kept resilient (as distinct from day-to-day incident troubleshooting, which lives in the companion support-runbook skill). Part of an enterprise handover documentation suite (see also: project-overview-doc, architecture-document, high-level-design, support-runbook, api-documentation, database-design, release-maintenance-guide) but fully usable standalone. - Skill: `vedkathe/operations-deployment-guide` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add vedkathe/operations-deployment-guide` - Raw SKILL.md: https://api.skillmd.com/api/skills/vedkathe/operations-deployment-guide/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: VedKathe (https://skillmd.com/u/vedkathe) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/vedkathe/operations-deployment-guide --- # Operations & Deployment Guide Generator Produce a single `.docx` document covering how a system gets deployed and how its infrastructure stays resilient — environments, CI/CD, deployment and rollback steps, configuration, secrets, backups, and DR. Day-to-day monitoring, logging, and incident troubleshooting belong in the companion `support-runbook` skill — don't duplicate that content here, cross-reference it instead. ## Sections (in this order) Cover page, Version History, Document Approval, Revision Log, and TOC are automatic — your `sections` array starts at "1. Environment Overview". | # | Section | Content | Diagram? | |---|---|---|---| | 1 | Environment Overview | Table: Environment (Dev/Staging/Prod/...), Purpose, URL, Access Method | | | 2 | Infrastructure Overview | Cloud provider(s), regions, compute/networking model | **Infrastructure Diagram**, **Network Diagram** | | 3 | Deployment Architecture | How services map onto infrastructure — containers, orchestration, load balancers, CDN | **Deployment Diagram** | | 4 | CI/CD Pipeline | Tool, stages (build/test/scan/deploy), triggers, approval gates | **CI/CD Pipeline Diagram** | | 5 | Deployment Procedure | Numbered, literal steps to deploy a release to each environment | | | 6 | Rollback Procedure | Numbered, literal steps to revert a bad deployment, including data/migration rollback | | | 7 | Configuration Management | Table of environment variables (name, description, example/default, secret?) and feature flags | | | 8 | Secrets Management | Where secrets live (vault/secrets manager), rotation policy, who can access them — never actual values | | | 9 | Backup Strategy | Table: Data store, frequency, retention, storage location | | | 10 | Disaster Recovery | RTO/RPO targets, failover process, who declares a disaster, communication plan | | | 11 | Appendix | Related runbook links, escalation contacts | | ## Diagram Policy **Applies to the `.docx` path only** — Markdown embeds Mermaid source directly instead of rendering anything (see "Output Format" below). Prefer a real Mermaid diagram — rendered via `mmdc` and embedded with `B.diagramImage()` — over `diagramPlaceholder()`, but only once you have concrete structure to draw (real names, not "TBD"). Read `references/diagram-generation.md` when you're actually about to render one — it has the full build order, the bundled config (`assets/mermaid-config.json`), the exact `mmdc` flags, and token-saving tips. Skip it entirely if this document ends up needing no diagrams. ## Missing Information Policy Never invent infrastructure details, deployment steps, or DR targets you have no basis for — a wrong-but-plausible deployment step is dangerous, not just inaccurate, since someone may follow it during an actual release. Use `toBeCompleted("...")` for sections you lack real input for, explaining what's needed, and still generate everything else. ## Output Format Ask the user which output format they want, unless they've already said so in this request (e.g., "as a docx", "in markdown," "just give me an .md file") — a quick single-choice question is enough, don't block on it otherwise: - **Word document (.docx)** — the default assumption if the person hasn't specified and their context suggests a formal deliverable. Follow "Using the builder" below. - **Markdown (.md)** — no script needed, write the file directly. Use these conventions so it stays structurally equivalent to the docx version: - Front matter: instead of a cover page, open with the title as an `#` heading, the project name as an italic subtitle line, then a metadata table instead of separate Version History / Approval / Revision Log tables: ```markdown # Operations & Deployment Guide *Acme Order Platform* | Field | Value | |---|---| | Version | 0.1 | | Author | Jane Doe | | Date | 2026-07-19 | | Status | Draft | | Approved By | Jane Doe (Tech Lead) | ``` - Headings: `#`/`##`/`###`/`####` matching the same section levels used in the table above — don't flatten everything to one level, that's what keeps the document skimmable and consistent with the docx version. - Tables: standard Markdown tables. - Diagrams — unlike the `.docx` path, don't render or embed an image here. Write the actual Mermaid source directly in a fenced code block; GitHub, GitLab, Obsidian, and most modern Markdown viewers render `mermaid` code blocks natively, so this is a real diagram, not a placeholder: ````markdown ```mermaid flowchart TD A[Client] --> B[API Gateway] B --> C[Order Service] C --> D[(Database)] ``` ```` Only fall back to a text placeholder if you don't yet have concrete enough detail to draw something real (mirrors `toBeCompleted` above): ```markdown > 📊 **DIAGRAM PLACEHOLDER — TO BE COMPLETED** > Not enough detail yet to draw the System Architecture Diagram — need > the actual component names and how they connect. ``` - "To be completed" callout — same blockquote treatment: ```markdown > ⚠️ **TO BE COMPLETED** > Explanation of what input is needed to fill this in. ``` - Save as `Operations_and_Deployment_Guide.md` instead of `Operations_and_Deployment_Guide.docx`. ## Workflow Ask the output format first (see "Output Format" above). For Markdown, skip straight to writing the file using those conventions — the numbered steps below describe the `.docx` path. 1. Gather what's available — CI/CD config files, infra-as-code, or ask directly about environments, deployment tooling, and DR targets. 2. Draft each section as data using the builder functions below. Write Deployment/Rollback Procedure as numbered steps, not prose — someone may need to follow them under pressure. 3. Build with `scripts/docx_builder.js`. 4. Skip PDF conversion by default — `docx_builder.js` is already tested and hardened (table widths and text alignment are enforced at the library level), so routine generations don't need a re-render just to confirm it worked. Only convert to PDF and view it if the user explicitly asks for visual verification, or if something about this generation is unusual (e.g., a new kind of content the library hasn't handled before, or a reported rendering problem). When you do need it: `soffice --headless --convert-to pdf .docx` (or `libreoffice --headless ...`), then `pdftoppm -jpeg -r 100 .pdf page` and view the images. 5. Save to `/mnt/user-data/outputs/Operations_and_Deployment_Guide.docx` (or `.md` if that's the chosen format) and present it. ## Using the builder (for the .docx path) This library requires the `docx` npm package. Before running any script, check it's available with `node -e "require('docx')"`; if that fails, install it with `npm install docx` in the working directory first — don't assume it's pre-installed, since that varies by environment. ```javascript const B = require("./scripts/docx_builder.js"); const sections = [ B.h1("1. Environment Overview"), B.table(["Environment", "Purpose", "URL", "Access Method"], [["Production", "Live traffic", "https://app.acme.com", "VPN + SSO"]], [2000, 2600, 2600, 2200]), B.h1("5. Deployment Procedure"), B.para("1. Merge the release branch into main after CI passes."), B.para("2. Trigger the \"Deploy to Production\" workflow and approve the gate."), B.para("3. Watch the rollout dashboard until all pods report healthy."), B.h1("9. Backup Strategy"), B.toBeCompleted("Backup schedule and retention weren't provided — check the database provider's backup configuration or ask the infra owner."), B.h1("10. Disaster Recovery"), B.table(["Metric", "Target"], [["RTO", "4 hours"], ["RPO", "1 hour"]], [4600, 4600]), ]; await B.buildDocument("/mnt/user-data/outputs/Operations_and_Deployment_Guide.docx", { docLabel: "Operations & Deployment Guide", title: "Operations & Deployment Guide", subtitle: "Acme Order Platform", versionHistory: [["0.1", "2026-07-19", "Jane Doe", "Initial draft"]], approvers: [["Jane Doe", "DevOps Lead", "", ""]], revisionLog: [], sections, }); ``` Available functions: `h1`/`h2`/`h3`/`h4`, `para`, `bullets`, `table(headers, rows, widths)`, `pageBreak`, `toBeCompleted(explanation)`, `diagramPlaceholder({name, purpose, recommendedContent, notes})`, and `buildDocument(path, options)`. Always use heading functions for titles so Word's Table of Contents and Navigation Pane work correctly. ## Success Criteria A DevOps or infrastructure engineer should be able to deploy a release, roll one back, and understand the system's resilience posture using only this document — without needing to ask the original team.