0da9e4c82d
- Move flat service manifests into structured subdirs (apps/, bootstrap-jobs/, repair-jobs/, migration-jobs/, validation-jobs/, node-ops/, networking/) - Retire oneoffs/ directories across services - Remove oceanus cluster and its host roles; add aether cluster + terraform scaffolding - Reorganize scripts/ into ops/, render/, sync/, manual-tests/ - Add Makefile with render/validate/test/flux targets and repo-structure tests - Update flux-system application CRs to the new paths - Add hermes-automated-triage-24h-plan knowledge doc (+ comms mirror) - Refresh knowledge catalogs, dashboards, vmalert rules, quality contract Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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/render/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?”
|
||
|