Skip to content

How to Contribute

Context

The Runbook is built through LLM-assisted brain-dump conversations. The process is designed so that Turbot HQ engineers can contribute knowledge without needing to write polished documentation from scratch.

How to Add or Update a Page

Start a conversation with an LLM (Claude) and say:

"I want to add something to the runbook about [topic]."

The LLM will use the runbook-contributor skill (in .skills/runbook-contributor/SKILL.md) to ask focused questions and produce a correctly structured page ready to commit.

Option 2 — Write Directly

Copy the page template below, fill it in, and submit a PR to the main branch.

# [Page Title]

## Context
Why this page exists. What problem or question it answers.

## Current State
What is true right now. Specific accounts, configs, decisions, versions.

## Decisions & Rationale
What was chosen and why. Alternatives considered and why they were rejected.

## Access & Ownership
Who has access to what, at what level. Who owns this. Who to contact.

## Related Pages
Links to other Runbook pages.

## External Links
Links to product docs, AWS docs, GitHub repos, etc.

## Last Updated
YYYY-MM-DD — [Your Name]

Writing Principles

  1. No pronouns without antecedents — name the thing explicitly every time
  2. Spell out acronyms on first use per page — each page is standalone
  3. State the obvious — tribal knowledge is exactly what needs capturing
  4. Prefer tables for access matrices, inventories, comparisons
  5. One concept per page — do not combine topics
  6. Explicit relationships — "This account belongs to the Orion OU in the turbot-master AWS Organizations"
  7. Include dates and versions for all infrastructure facts

Where Does New Content Go?

See What Goes Here vs Product Docs for the boundary.

For section placement, use this guide:

Content type Section
New engineer setup Getting Started
Cloud/org structure Our Setup
Hosting, backups, recovery of a product Infrastructure → [Product]
Guardrails workspace, mods, policies internally Guardrails @ Turbot HQ
Who gets access to what Identity & Access
Terraform, GitHub Actions, tooling Automation & Tooling
Cloud spend decisions Cost & Optimization
Incident or outage Incident & Ops Log
Demo environments Demos & Customer Environments
Specific customer engagement Customer Engagements
Quick lookup, glossary Reference

Publishing

Merging to main auto-publishes via GitHub Actions → GitHub Pages. No manual steps required.

Last Updated

2026-04-04 — Venu