Runbook Portability: Why Plain Text Always Wins

Your runbook is useless if you can’t access it when you need it. Plain text ensures your documentation works everywhere, every time.

This guide explores runbook portability and why it matters. For format comparisons, see why markdown wins for runbooks.

The Portability Problem

Imagine this scenario:

It’s 3am, production is down
You’re SSH’d into a bastion host
You need your runbook for the recovery procedure
Your runbook is in… Confluence? Jupyter? A proprietary tool?

Can you access it?

Common Portability Failures

Format/Tool	Failure Mode
Confluence	Needs browser, auth, network
Notion	Needs browser, auth, network
Jupyter	Needs Python, Jupyter installed
VS Code Notebook	Needs VS Code, extensions
Proprietary tool	Needs specific software

What Works Everywhere

Format	Requirements
Plain text	Text editor (or `cat`)
Markdown	Text editor (pretty in GitHub/GitLab)
Org-mode	Text editor (or Emacs for full features)

Dimensions of Portability

1. Reader Portability

Can anyone read it without special software?

# Good: Markdown
## Check Pod Status
```bash
kubectl get pods
```

# Also Good: Plain text
CHECK POD STATUS
================
Run: kubectl get pods

// Bad: Jupyter JSON
{"cells":[{"cell_type":"code","source":["!kubectl get pods"]}]}

2. Platform Portability

Does it work on all operating systems?

Format	Linux	macOS	Windows	Mobile
Markdown	✅	✅	✅	✅
Plain text	✅	✅	✅	✅
Jupyter	✅	✅	⚠️	❌
VS Code	✅	✅	✅	❌

3. Tool Portability

Can you view/edit it with different tools?

Markdown works in:

Any text editor
GitHub/GitLab web UI
VS Code, Sublime, Vim
Obsidian, Typora
Static site generators
Documentation platforms

Notebooks require:

Jupyter (or compatible)
Specific extensions/kernels

4. Network Portability

Does it work offline?

Format	Offline Viewing	Offline Editing
Local markdown	✅	✅
Git-cloned repo	✅	✅
Confluence	❌	❌
Cloud notebook	❌	❌

5. Time Portability

Will it still work in 5 years?

Plain text has been readable for 50+ years. Proprietary formats come and go.

# This will still work in 2030
cat runbook.md

# This might not
some-vendor-tool open runbook.propformat

Achieving Maximum Portability

Store Runbooks in Git

operations/
├── runbooks/
│   ├── api-recovery.md
│   ├── db-failover.md
│   └── incident-response.md
└── README.md

Benefits:

Clone to any machine
Works offline
Version history
Access control via git permissions

Use Standard Markdown

Avoid platform-specific extensions:

# Good: Standard Markdown
## Step 1: Check Status
```bash
kubectl get pods
```

# Avoid: Platform-Specific
:::warning
This only renders in some tools
:::

Include Fallback Instructions

If someone can’t run the fancy version, they should still succeed:

# Pod Recovery Runbook

This runbook can be executed with Stew, or manually by copying
commands to your terminal.

## Step 1: Check current state

```bash
kubectl get pods -l app=api
```

Copy and run the above command. You should see output like:
```
NAME                   READY   STATUS    RESTARTS   AGE
api-7d4f8b6c9-x2k4j   1/1     Running   0          2d
```

Test Portability

Periodically verify your runbooks work in degraded conditions:

## Runbook Portability Checklist

- [ ] Can view via `cat` or `less`
- [ ] Can read on GitHub without cloning
- [ ] Commands are complete (no hidden context)
- [ ] Works without internet (if cloned)
- [ ] No proprietary format dependencies

The Portability vs. Features Tradeoff

Rich features often sacrifice portability:

Feature	Portability Cost
Inline execution	Requires runtime
Rich visualizations	Requires renderer
State between cells	Requires notebook
Interactive widgets	Requires JavaScript

The key is choosing the right tradeoff for each use case.

High Portability (Emergency Runbooks)

# Database Failover

## 1. Promote replica
```bash
pg_ctl promote -D /var/lib/postgresql/data
```

## 2. Update connection strings
Update these files:
- /etc/app/database.yml
- /etc/worker/database.yml

Balanced (Regular Operations)

# Regular maintenance runbook with Stew execution
# Falls back to copy-paste if Stew unavailable

Low Portability (Analysis Notebooks)

# Jupyter notebook with pandas, matplotlib
# Acceptable for non-emergency analysis work

Stew’s Portability Philosophy

Stew enhances portability rather than limiting it:

Your runbooks are markdown files:

Store them anywhere
Read them with any tool
Edit them with any editor

Stew adds execution:

Run commands when Stew is available
Fall back to copy-paste when it’s not

No lock-in:

Standard markdown format
No proprietary extensions required
Export/migration is trivial (it’s just files)

# This is a Stew runbook
# It's also valid markdown
# It works with or without Stew

## Check pods
```bash
kubectl get pods
```

Your runbooks remain portable. Stew makes them more powerful when available.

Join the waitlist and build runbooks that work everywhere.