From Static Wikis to Interactive Docs

Your wiki is full of runbooks. Some are accurate. Some were accurate two years ago. You’re not sure which is which.

Moving from static wikis to interactive documentation solves this, but migration can feel daunting. Here’s how to do it without disrupting your team.

Why Migrate?

Before diving into how, let’s revisit why:

Static Wikis	Interactive Documentation
Commands decay silently	Broken commands fail visibly
Copy-paste errors	Click to execute
No execution history	Full audit trail
Read and switch contexts	Execute in place
Trust erodes over time	Trust builds with use

The goal isn’t to move documents from one place to another. It’s to transform documentation from something you read into something you use.

Phase 1: Audit What You Have

Start by understanding your current documentation landscape.

Inventory Your Runbooks

List every operational procedure in your wiki:

## Current Runbooks Audit

### Deployment
- [ ] Production deploy (Confluence: /wiki/deploy-prod)
- [ ] Staging deploy (Confluence: /wiki/deploy-staging)
- [ ] Rollback procedure (Confluence: /wiki/rollback)

### Incident Response
- [ ] Database failover (Confluence: /wiki/db-failover)
- [ ] API restart (Confluence: /wiki/restart-api)
- [ ] Cache flush (Notion: /cache-operations)

### Maintenance
- [ ] Certificate rotation (Google Doc)
- [ ] Secret rotation (Confluence: /wiki/rotate-secrets)

Assess Each Document

For each runbook, note:

Last updated: When was it last modified?
Last used: When was it last actually run?
Accuracy: Is it still correct?
Criticality: How important is this procedure?

Prioritize by Impact

Focus migration on:

High-criticality, frequently-used procedures
Incident response runbooks
Onboarding procedures
Everything else

Phase 2: Set Up Your New Structure

Before migrating content, establish where interactive documentation will live.

Choose a Repository

Create a dedicated repo or directory:

# Dedicated repo
git init company-runbooks
cd company-runbooks

# Or directory in existing repo
mkdir -p ops/runbooks

Define Organization

Create a logical structure:

runbooks/
├── README.md           # Index of all runbooks
├── deploy/
│   ├── production.md
│   ├── staging.md
│   └── rollback.md
├── incident-response/
│   ├── database-failover.md
│   ├── api-restart.md
│   └── cache-flush.md
└── maintenance/
    ├── rotate-certificates.md
    └── rotate-secrets.md

Create Templates

Standardize how interactive documentation looks:

---
title: [Procedure Name]
owner: [Team]
last-tested: [Date]
---

# [Procedure Name]

## Overview
Brief description of what this procedure does and when to use it.

## Prerequisites
- [ ] Prerequisite 1
- [ ] Prerequisite 2

## Procedure

### Step 1: [Description]

```bash
command here
```

### Step 2: [Description]

```bash
command here
```

## Verification

```bash
verification command
```

## Rollback

If something goes wrong:

```bash
rollback command
```

Phase 3: Migrate Content

Now convert static wiki content to interactive documentation.

Start with One High-Value Runbook

Don’t try to migrate everything at once. Pick your most critical procedure and convert it first.

From static wiki:

# API Restart Procedure

1. Check current pod status by running:
   kubectl get pods -n production -l app=api

2. Trigger a rolling restart:
   kubectl rollout restart deployment/api -n production

3. Watch the rollout:
   kubectl rollout status deployment/api -n production

To interactive documentation:

---
title: API Restart
owner: platform-team
last-tested: 2024-01-15
---

# API Restart

## Prerequisites
- [ ] Connected to production cluster
- [ ] Verified this is the correct cluster: `kubectl config current-context`

## Procedure

### Check Current Pod Status

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

### Trigger Rolling Restart

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

### Watch Rollout Progress

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

## Verification

Confirm all pods are healthy:

```bash
kubectl get pods -n production -l app=api --field-selector=status.phase=Running
```

Test the Migrated Runbook

Run through the procedure in a safe environment. Fix any issues before moving on.

Migrate Incrementally

Convert 2-3 runbooks per week. This pace:

Keeps the project manageable
Allows learning from each migration
Doesn’t overwhelm the team

Phase 4: Redirect and Retire

As you migrate runbooks, handle the transition.

Update Wiki Links

Add redirects from old wiki pages:

# API Restart Procedure

⚠️ This document has moved to interactive documentation.

**New location:** [runbooks/incident-response/api-restart.md](link-to-repo)

This wiki page will be deleted on [date].

Set Deprecation Dates

Give teams time to adjust:

Week 1: Add redirect notice
Week 4: Remove content, keep redirect
Week 8: Delete wiki page

Archive, Don’t Delete

Keep old wiki content accessible during transition:

wiki-archive/
├── api-restart-2024-01-01.md
├── db-failover-2024-01-01.md
└── ...

Phase 5: Build New Habits

Migration isn’t just moving files—it’s changing how your team works.

Train the Team

Show engineers how to:

Find interactive documentation
Run procedures step-by-step
Update procedures after incidents
Create new runbooks

Update Incident Process

Modify your incident response process:

## When Paged

1. Acknowledge the page
2. Open relevant runbook from `ops/runbooks/`
3. Execute procedure step-by-step
4. If runbook is missing or broken, note for post-incident

Require Runbook Updates

After every incident:

Was there a runbook?
Did it work?
What needs to change?

Make runbook updates part of incident closure.

Common Migration Pitfalls

Trying to Migrate Everything

You don’t need to convert every wiki page. Conceptual documentation can stay in the wiki. Focus on operational procedures.

Perfect vs. Good

Don’t over-engineer the first pass. A simple interactive runbook that works beats a comprehensive one that’s never finished.

Forgetting Testing

Migrated documentation needs validation. Run through procedures before declaring them ready.

Not Retiring Old Docs

Parallel systems cause confusion. When a procedure moves to interactive documentation, remove or redirect the wiki version.

The End State

After migration, your team has:

One source of truth for operational procedures
Tested, executable documentation
Version-controlled procedures that go through code review
Audit trails for compliance and post-incident review
Confidence that procedures work because they’re actually used

Static wikis become what they should be: background information and context. Executable procedures live in interactive documentation.

Stew makes this transition seamless. Write Markdown, execute step-by-step, version control with Git.

Join the waitlist and start your migration to interactive documentation.