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?”
|
|||
|
|
|