---
title: "KB authoring: what to write (and what not to)"
tags: ["atlas", "kb", "runbooks"]
owners: ["brad"]
entrypoints: []
source_paths: ["knowledge/runbooks", "scripts/knowledge_render_atlas.py"]
---

# KB authoring: what to write (and what not to)

## The goal
Give Atlas assistants enough grounded, Atlas-specific context to answer “how do I…?” questions without guessing.

## What to capture (high value)
- User workflows: “click here, set X, expected result”
- Operator workflows: “edit these files, reconcile this kustomization, verify with these commands”
- Wiring: “this host routes to this service; this service depends on Postgres/Vault/etc”
- Failure modes: exact error messages + the 2–5 checks that usually resolve them
- Permissions: Keycloak groups/roles and what they unlock

## What to avoid (low value / fluff)
- Generic Kubernetes explanations (link to upstream docs instead)
- Copy-pasting large manifests (prefer file paths + small snippets)
- Anything that will drift quickly (render it from GitOps instead)
- Any secret values (reference Secret/Vault locations by name only)

## Document pattern (recommended)
Each runbook should answer:
- “What is this?”
- “What do users do?”
- “What do operators change (where in Git)?”
- “How do we verify it works?”
- “What breaks and how to debug it?”