35 lines
1.3 KiB
Markdown
35 lines
1.3 KiB
Markdown
---
|
||
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?”
|
||
|