p24-infra Docs

2640-docs-restructure-p24-infra-docs

2 min read

Design — Docs Restructure + p24-infra-docs Repo Split

Issue: #2640 · Status: Design (plan only) · Batch: K (#3338)

Plan to reorganise docs/ and evaluate extracting it into a standalone p24-infra-docs repository.

1. Why

docs/ has no runtime dependency on the rest of the repo — a natural extraction candidate. Today it holds 150+ loose Markdown files at the top level plus a partial NN-* numbered taxonomy (01-architecture … 18-workbooks) and topic subdirs (designs/, plans/, playbooks/, roles/, servers/, incidents/, …). The two schemes coexist inconsistently, so files are hard to locate.

2. Stage 1 — Reorganise in place (this repo, low risk)

Target the existing numbered taxonomy as the canonical home; treat top-level loose files as a backlog to file into it.

  • Adopt docs/NN-* numbered sections as canonical; document the scheme in docs/index.md.
  • Sweep top-level loose *.md into the right numbered section (e.g. n8n-* → 11-automations, *-operations.md → 03-operations, secrets-* → 06-secrets).
  • Keep working subdirs (designs/, plans/, playbooks/, adr/) as-is — they are already coherent.
  • Update internal cross-links after each move (grep for the old relative path).
  • Confirm docs/projects/ (added 2026-07-02) is complete for all six projects.

Guard rail: move files in small, link-fixing commits — never a single bulk git mv. Broken CLAUDE.md / playbook cross-links are the main regression risk.

3. Stage 2 — Extract p24-infra-docs (higher risk, deferred)

Only after Stage 1 stabilises. Options, in order of recommendation:

OptionSync mechanismProsCons
A. git subtree (recommended)git subtree split/push on docs/history preserved, no submodule friction, docs stay browsable in-repomanual push step
B. submodule.gitmodules pointerclean separationcontributor friction, detached-HEAD footguns
C. CI mirrorGH Action copies docs/ on changezero contributor impactone-way, diverges if edited in docs repo

Boundary after split

p24-infra (core):  monitoring/ infra-src/ secrets/ ansible/ scripts/ .github/
p24-infra-docs:    docs/ + CLAUDE.md ecosystem instructions

Open decisions (human)

  • CHANGELOG.md — stays in p24-infra (tracks code/infra releases) or moves to docs repo.
  • Repo name: p24-infra-docs vs p24-docs.
  • Whether the split is worth it at all — Stage 1 alone may resolve the discoverability pain, and a second repo adds a sync surface. Recommendation: ship Stage 1, then re-evaluate Stage 2 need.

4. Out of scope

No new repo is created and no files are moved by this issue — it produces the plan and the decision list only.

Design-only deliverable. Related: docs/index.md, CLAUDE.md §Full Documentation.

Graph View