Skip to content

Documentation Layout

Documentation in this repository is split by layer, each with a fixed responsibility. The goal is that "where do I write this?" is a mechanical decision, not a judgment call. The basic rule: never write the same fact in two places.

Human-facing and AI-facing aren't "two zones" — they're "one source → two outputs": every fact is written exactly once, in docs/. The MkDocs build produces two outputs from that one source — a human-facing HTML site (overviews, diagrams, narrative) and an AI-facing /llms.txt (index) + /llms-full.txt (full text), auto-generated by mkdocs-llmstxt (the llmstxt.org standard). The docs site's nav is human-only, so no audience label is attached to anything. .claude/rules/ stays thin and points at docs/; agent-facing task instructions live in the root AGENTS.md / CLAUDE.md (facts are never duplicated).

The five layers

Layer Role Location Contains Does not contain
Top README Reference portal /README.md The big picture, hardware, entry links into every layer, the outward-facing "what is this" Detailed how-tos, decision rationale, component specs
Per-directory README Co-located what / where kubernetes/<cat>/README.md, kubernetes/<cat>/<comp>/README.md What this directory is, which components live here, where to dig deeper in docs/ Cross-cutting background, decision rationale (belongs in an ADR)
docs/ (MkDocs source of truth) The human-facing source of truth for cross-cutting how / why docs/<topic>/ Detailed matrices, workflows, diagrams, explanations spanning multiple components The history of decisions (link to the ADR instead), file-layout conventions
docs/adr/ Why (immutable decision records) docs/adr/NNN-*.md The context behind a decision, rejected alternatives, trade-offs, Consequences Current file paths, how-tos (these get stale)
.claude/rules/ Thin AI-facing summary + globs .claude/rules/<topic>.md 3–5 line rules, the applicable glob, a link into docs/ Detailed tables (belongs in docs/), human-oriented explanation
CLAUDE.md The AI entry point /CLAUDE.md Mandatory constraints, an index into rules/, the directory tree The tech-stack table (belongs in the Top README), layout details (belongs in the per-dir README)

Topic → source-of-truth map

The definitive answer to "where is this information documented." When adding new information, use this table first to decide where it goes.

Topic Source of truth Where to find a summary
Per-domain architecture (argocd / auth / network / secrets / storage / observability / backstage) kubernetes/<cat>/README.md (Model A: docs/architecture/<cat>.md transcludes it. storage includes R2 backups, RecurringJobs, and StorageClasses) The corresponding topic under .claude/rules/
Secret management (the matrix of the 4 methods, inventory, operational procedures) docs/secret-management/index.md (architecture and design rationale live in kubernetes/secrets/README.md — a deliberate split of responsibilities) .claude/rules/security-secrets.md
Backstage Golden Path (procedures for App Developers) docs/architecture/backstage-golden-path.md kubernetes/backstage/README.md, .claude/rules/environment-separation.md
Namespace naming docs/adr/006-namespace-naming.md (why) + .claude/rules/environment-separation.md (how) kubernetes/namespaces/README.md
Helm multi-source layout convention kubernetes/README.md (Pattern A/B) .claude/rules/helm-multisource.md
GitOps workflow .claude/rules/gitops-workflow.md CLAUDE.md Mandatory Constraints
Cluster topology (nodes, labels, scheduling) .claude/rules/kubernetes-cluster.md kubernetes/README.md
Tech stack Top README.md docs/index.md

Two Material behaviours have already cost time here, so they are written down rather than rediscovered.

  • navigation.indexes only folds a section's overview into the section name when the first child is a real index.md file. A first child named anything else stays a separate row, showing its own h1 — which for a transcluded domain README is a full thesis sentence that wraps. This is why every domain overview lives at architecture/<domain>/index.md. With use_directory_urls (the default), foo.md and foo/index.md produce the same /foo/ URL, so moving a page into that shape costs nothing
  • content.action.view builds its link from edit_uri, replacing edit with raw. Removing edit_uri removes the button too, and there is no setting that points it at GitHub's blob view

Language

Prose and code are written in different languages here, and the split is deliberate rather than accidental. Measured across the repository in 2026-09:

What Language Measured
docs/** and the READMEs the site transcludes English 2% and 6% of files contain any Japanese, and what remains is Zenn article titles and the brand's own word, 研鑽
Comments inside code — values.yaml, .tf, .go, .tsx, .sh Japanese 64% of YAML, 100% of Terraform, 87% of Go, 77% of TSX, 52% of shell
CLAUDE.md, AGENTS.md, .claude/rules/, .claude/skills/ Japanese 70% of files — these are read by agents and by the author, not by visitors

So a README may point a reader at an annotated values.yaml and that file will be commented in Japanese. That is the convention, not an oversight. If a component's configuration needs to be explained to a visitor, the explanation belongs in the README or in docs/, in English — not in a translation of the comments.

Rendering target

Every layer above is Markdown, but not every file is read in the same place. Each file has exactly one rendering target, and that decides which Markdown you may write in it.

Files Read on May use
docs/**/*.md The docs site only — the top README links to https://yu-min3.github.io/kensan-lab/…, never to ./docs/*.md Everything MkDocs Material offers: admonitions, content tabs, attr_list, <figure markdown>
Every file transcluded by docs/** — the per-domain kubernetes/**/README.md, plus bootstrap/** and environments/kind/README.md Both github.com and the docs site Only what both engines agree on: CommonMark, plain HTML, tables, Mermaid. Cross-references must be absolute github.com URLs: a relative path cannot resolve from both the file's own directory and docs/
Everything else — the top README.md, apps/**, .claude/, sample data, scaffold templates github.com only, or not read as prose at all Whatever renders on GitHub; no site constraint applies

The second row is the constrained one, and it is constrained for a reason: Material's extensions are not errors on GitHub, they are passed through as literal text. A page keeps building while displaying its own source. docs/showcase.md shipped that way for 17 days before anyone opened it on GitHub (PR #468).

Prose that operators read — the bootstrap Terraform and the explore layer — used to sit in the third row, reachable only on github.com. It has been moved into the second: written once beside the code it describes, and transcluded onto the site. There are now two source systems, not three.

In practice the constraint costs nothing — domain READMEs are written with diagrams, tables, and prose, all of which render identically on both. scripts/check-github-render.py enforces it in CI, deriving the file list from the --8<-- lines under docs/ so a tenth architecture page is covered without anyone updating a list.

How to decide where something goes

When unsure where a fact belongs, walk through this flow:

Is it "the reason behind a decision"?
  └─ Yes → an ADR (docs/adr/)
  └─ No  → Is it "an explanation self-contained within one specific directory"?
            └─ Yes → that directory's README.md
            └─ No  → Is it "cross-cutting how / why spanning multiple components"?
                      └─ Yes → docs/<topic>/
                      └─ No  → Is it a rule the AI needs, scoped by a glob?
                                └─ Yes → .claude/rules/<topic>.md
                                └─ No  → It probably doesn't need to be written down at all

README writing guide

kubernetes/<cat>/README.md and kubernetes/<cat>/<comp>/README.md should satisfy the following.

  • Length: aim for 25–50 lines, and treat 80 as the ceiling. Past that, the content is not a co-located note any more — push it to docs/, or link to the annotated values.yaml instead of restating it
    • Exception — architecture-category READMEs (the kubernetes/<cat>/README.md files that are the transclude source for docs/architecture/<cat>/index.md): since these double as the site's architecture-page source of truth, up to ~150 lines plus a mermaid diagram is acceptable. Use network as the template (Design thesis → Components → diagram → Design rationale → Related)
    • The number moved from "5–30" to this in 2026-09, after measuring. Every README that reached the site sat at 63–149 lines and none exceeded its budget; the six that had grown past theirs were all files the site never published — tempo at 442 lines and otel-collector at 408 among them, mostly restating the domain README and the integration runbook. The rule was never what kept them short; being published was. So the number now matches the grain the published ones actually hold, and the second source system was folded into the first so nothing sits outside that pressure again
  • Required sections:
  • A one-line summary (what this directory / component is)
  • A description of the subdirectories / key files it contains
  • Deep-dive links (related docs/, ADRs, external URLs)
  • Forbidden:
  • An empty template with only TODOs
  • Detail tables that duplicate content living elsewhere (link to it instead)
  • A walkthrough of the component's own values.yaml. The file is annotated; link to it
  • Restating what the upstream project documents. Link to upstream instead
  • "Why" explanations (those belong in an ADR)

Minimal component README template

# <component>

<one-line summary — why this exists>

## Layout

- `values.yaml` — the key Helm chart overrides (just the highlights)
- `resources/` — additional manifests outside the chart (HTTPRoute, SealedSecret, …)

## Related

- Deep dive: [docs/<topic>/index.md](../../../docs/<topic>/index.md)
- Decision history: [ADR-NNN](../../../docs/adr/NNN-*.md)

Preventing drift

Making each fact's source of truth unique prevents drift structurally. No CI check or linter is needed — because duplication itself doesn't exist.

That said, keep the following habits:

  • Come back to this page to decide placement whenever you write a new fact
  • When editing existing docs, get in the habit of suspecting "this fact probably exists somewhere else too"
  • If you find a violation, consolidate it into the source of truth promptly and replace the other spot with a link