Build Interactive Docs for DevOps Workflows

You’re convinced that interactive documentation is better than static wikis. Now what?

Building interactive documentation for DevOps workflows isn’t complicated, but it requires intentional structure. Here’s how to do it right.

Start with the Right Format

Interactive documentation needs a format that’s:

• Human-readable
• Machine-parseable
• Version-controllable
• Portable

Markdown fits all four criteria:

# Restart API Service

Check pod status before restarting:

​```bash
kubectl get pods -n production -l app=api
​```

Trigger rolling restart:

​```bash
kubectl rollout restart deployment/api -n production
​```

Avoid proprietary formats. Your interactive documentation should work in any text editor, survive tool migrations, and live in Git.

Structure for Execution

Interactive documentation isn’t just documentation with code blocks. It needs structure that supports step-by-step execution.

Use Clear Section Headers

Each major step gets its own section:

## Pre-flight Checks

Verify you're targeting the correct cluster:

​```bash
kubectl config current-context
​```

## Execute Restart

​```bash
kubectl rollout restart deployment/api -n production
​```

## Verify Success

​```bash
kubectl rollout status deployment/api -n production
​```

One Command Per Block

Don’t combine multiple commands in one block:

# Bad - multiple commands
​```bash
kubectl get pods -n production
kubectl get services -n production
kubectl get deployments -n production
​```

# Good - one command per block
## Check Pods
​```bash
kubectl get pods -n production
​```

## Check Services
​```bash
kubectl get services -n production
​```

## Check Deployments
​```bash
kubectl get deployments -n production
​```

Separate blocks let you run steps individually and see output for each.

Add Decision Points

Real procedures involve decisions. Make them explicit:

## Check Replica Count

​```bash
kubectl get deployment api -n production -o jsonpath='{.spec.replicas}'
​```

**If replicas < 3:** Scale up before proceeding
**If replicas >= 3:** Continue to next step

## Scale Up (if needed)

​```bash
kubectl scale deployment/api -n production --replicas=3
​```

Handle Environment Differences

DevOps workflows run in multiple environments. Your interactive documentation should handle this.

Use Variables

Document required variables clearly:

# Deploy Service

## Required Variables
- `NAMESPACE`: Target namespace (e.g., `staging`, `production`)
- `VERSION`: Docker image tag to deploy

## Deploy

​```bash
kubectl set image deployment/api api=myregistry/api:$VERSION -n $NAMESPACE
​```

Create Environment-Specific Files

For significantly different workflows, use separate files:

runbooks/
├── deploy-staging.md
├── deploy-production.md
└── deploy-shared-steps.md

Document Environment Requirements

Be explicit about prerequisites:

# Production Database Failover

## Prerequisites
- [ ] VPN connected to production network
- [ ] `kubectl` context set to `prod-cluster`
- [ ] DBA approval in incident channel
- [ ] Maintenance window scheduled

## Verify Context

​```bash
kubectl config current-context
# Expected: prod-cluster
​```

Include Safety Measures

Interactive documentation can run dangerous commands. Build in safety.

Dry-Run First

## Delete Failed Pods

Preview what will be deleted:

​```bash
kubectl delete pods --field-selector=status.phase=Failed -n production --dry-run=client
​```

⚠️ Review the output above before proceeding.

Execute deletion:

​```bash
kubectl delete pods --field-selector=status.phase=Failed -n production
​```

Add Warnings

## Drop Database Table

⚠️ **DESTRUCTIVE OPERATION** ⚠️

This permanently deletes all data in the sessions table.
Ensure you have a recent backup before proceeding.

​```bash
psql $DATABASE_URL -c "DROP TABLE sessions;"
​```

Include Rollback Steps

Every change should have an undo:

## Enable Feature Flag

​```bash
curl -X POST https://api.internal/flags/new-checkout -d '{"enabled":true}'
​```

### Rollback

If issues arise, disable immediately:

​```bash
curl -X POST https://api.internal/flags/new-checkout -d '{"enabled":false}'
​```

Organize Your Documentation

As you build interactive documentation, organization matters.

By Service

runbooks/
├── api/
│   ├── restart.md
│   ├── scale.md
│   └── debug-latency.md
├── database/
│   ├── failover.md
│   └── restore-backup.md
└── cache/
    └── flush.md

By Workflow

runbooks/
├── deploy/
│   ├── production.md
│   └── staging.md
├── incident-response/
│   ├── high-latency.md
│   └── database-down.md
└── maintenance/
    ├── rotate-secrets.md
    └── update-certificates.md

Add an Index

Create a README that links to all runbooks:

# Runbooks

## Deployment
- [Production Deploy](deploy/production.md)
- [Staging Deploy](deploy/staging.md)

## Incident Response
- [High Latency](incident-response/high-latency.md)
- [Database Down](incident-response/database-down.md)

Version Control Everything

Interactive documentation belongs in Git:

# Initial setup
git init runbooks
cd runbooks
git add .
git commit -m "Initial runbook documentation"

# Changes go through PRs
git checkout -b update-deploy-procedure
# ... edit files ...
git commit -m "Update deploy procedure for new cluster"
git push origin update-deploy-procedure
# Create PR, get review, merge

Benefits:

• Change history for all procedures
• Code review for runbook updates
• Rollback capability
• Branch-based workflows for testing changes

Choose Your Execution Tool

Markdown is the format; you need a tool to make it interactive. Requirements:

1. Parse Markdown — Recognize code blocks as executable cells
2. Run commands — Execute in terminal or over SSH
3. Show output — Display results inline
4. Maintain state — Track which steps have run
5. Handle errors — Let you investigate and retry

Stew does all of this. Write your Markdown, open in Stew, execute step-by-step.

Start Small, Expand Gradually

Don’t try to convert all documentation at once:

1. Pick one critical procedure (e.g., production restart)
2. Write it as interactive documentation
3. Use it next time you need that procedure
4. Improve based on experience
5. Add the next procedure

Within a few weeks, you’ll have a library of battle-tested interactive documentation.

Join the waitlist and start building interactive documentation today.