Restructuring Existing Documentation onto FCC¶

This tutorial is for teams with a mature documentation set — dozens to hundreds of Markdown files, a sprawling docs/ tree, maybe a Sphinx or MkDocs site that has accumulated five years of organic growth — who now want to retrofit their docs onto the FCC R.I.S.C.E.A.R.-aligned structure without a full rewrite.

You will end this tutorial with:

A complete docs inventory classified by audience tier.
A persona map from your authors and reviewers to FCC's 164 personas.
An FCC Find / Create / Critique phase assignment for every chapter.
A quality-gate selection from the PHOENIX 58-gate registry.
A working cross_reference.yaml scaffold that wires your personas into each other.
A _quarto.yml extension so your existing docs publish through the FCC publication pipeline alongside FCC's own book series.
An audience-tier cascade (for-beginners/, for-professionals/, for-auditors/, ...) that rehomes every existing file.

This is a lot. Do not try it in one sitting. Budget 4–6 hours for the first pass (inventory + persona map + phase assignment) and 2–3 days of wall-clock time for the full retrofit on a project with a few hundred docs pages.

Motivation — why restructure at all?¶

Organic docs trees have three systemic problems that FCC fixes:

No audience discipline. A single page is written simultaneously for beginners, professionals, and auditors — nobody is well served. FCC's audience-tier cascade (for-beginners, for-professionals, for-auditors, for-knowledge-engineers, for-data-architects, for-scientists, for-educators) forces you to choose an audience per page and signpost cross-links for everyone else.
No lifecycle discipline. Every page is "current" simultaneously — there is no explicit Find / Create / Critique phase per chapter. FCC ties each chapter to a phase, which in turn ties it to a workflow graph node, which in turn ties it to a quality gate.
No governance discipline. Who approves a docs change? Who reviews a policy change? Under FCC, every doc is authored, reviewed, and approved by a named persona (the persona is a role, not a person — one human usually wears several hats) — and the PHOENIX 58-gate registry provides the acceptance criteria.

The evidence base for this retrofit:

PHOENIX 58 gates (vendored in FCC since v1.3.8) define the acceptance criteria for every quality-gate-bearing document. See docs/phoenix/ and src/fcc/governance/gates.py.
Zachman cross-cut (v1.4.1 ice_ext absorption, ADR-011) gives every persona a canonical (row, column) classification — a 6-row × 6-column matrix that tells you who cares about this doc and from what perspective.
Audience-tier cascades (v1.2.x onward) are the FCC convention for routing the same content across multiple audiences.

Step 1 — Docs inventory¶

Start with a raw inventory. You cannot restructure what you cannot see.

# From your project root:
find docs -type f \( -name "*.md" -o -name "*.rst" -o -name "*.qmd" \) \
  -printf "%p\t%s\t%TY-%Tm-%Td\n" | sort > docs-inventory.tsv

This gives you a TSV with path, size, and last-modified date for every docs file. Load it into a spreadsheet and add four columns:

Column	Values	Purpose
`audience`	beginner / professional / auditor / scientist / knowledge-engineer / data-architect / educator	Target reader
`lifecycle`	find / create / critique	FCC phase
`owner_persona`	FCC persona ID (see Step 2)	Accountable role
`zachman_cell`	`{ARCHITECT,ENGINEER,EXECUTIVE,MANAGER,OPERATOR,PLANNER}/{WHAT,HOW,WHERE,WHO,WHEN,WHY}`	Cross-cut coordinate

Do not skip any file. A README.md that nobody reads is still an input to the restructure.

When you classify by audience, resist the temptation to label everything "professional" — that is a drift smell. A real inventory has 40–60% professional, 15–25% beginner, 10–20% auditor, and the remainder split across the specialist audiences. If your inventory is 90% "professional" your docs are undifferentiated and the cascade is precisely what you need.

Step 2 — Persona mapping¶

FCC ships 164 personas across 20 core categories + 6 vertical packs. You do not need all 164; most teams use 15–25. The goal is to map each of your existing authors and reviewers to exactly one FCC persona (they can wear multiple persona hats, but each hat has one wearer at a time on a given change).

Load the registry and scan categories:

from fcc._resources import get_personas_dir
from fcc.personas.registry import PersonaRegistry

registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
print(f"{len(registry)} personas across {len(registry.by_category())} categories")

for category, personas in sorted(registry.by_category().items()):
    print(f"  {category}: {len(personas)}")
    for p in personas[:3]:
        print(f"    - {p.id}: {p.name}")

Categories that are load-bearing for a docs retrofit:

docs_as_code — Content Master Weaver (CMW), Too-Long-Didn't-Read summarizer (TLDR), Visual Design Stylist (VDS).
open_science — Open-Science Curator (OSC), FAIR workflow stewards.
privacy — Privacy Handoff Validator (PHV).
governance — Governance Reviewer, Decision Archaeologist (DAR).
stakeholder — Stakeholder personas for audience liaison.
integration — Liaison personas where your docs touch another system.

Use the codename decoder to look up any codename you see in the registry (PHOENIX, POLARIS, LYRA, NEXUS, etc.) — the decoder explains what each codename means and why.

For each author in your contributor list, answer three questions:

What do they produce? (Which R.I.S.C.E.A.R. "Expected Output" fits?)
What phase do they work in? (Find / Create / Critique)
Who do they collaborate with? (Role Collaborators)

Map their answers to a persona. If no persona fits, you have found a gap; propose a custom persona (see Step 3 of integrating-fcc-into-mature-codebase.md).

Step 3 — Workflow-graph extraction¶

FCC's workflow-graph engine ships seven graphs:

Graph	Nodes	Use for
base	5	Simplest scenario — Research, Draft, Review, Revise, Approve
extended-20	20	Typical multi-persona docs project
extended-24	24	Adds stakeholder + governance nodes
extended-55	55	Full multi-audience cascade
extended-84	84	Largest FCC graph — research-heavy regulated-industry docs
eaifc-solution	—	EAIFC solution-level scenarios
eaifc-solution-extended	—	EAIFC with stakeholder threads

For a docs retrofit, start with extended-20. Read your inventory column by column and assign each file to one of these FCC phases:

Find. Research briefs, decision logs, ADR drafts, literature surveys, evidence inventories, discovery notes.
Create. Chapters, how-tos, references, tutorials, API docs, architecture descriptions, design records.
Critique. Review checklists, audit reports, compliance attestations, quality-gate evidence, CI logs, post-mortems.

Feedback edges in the FCC extended graph flow Critique → Find and Critique → Create (see the FCC Cycle tutorial). A docs retrofit that preserves those edges keeps your critique feedback loopable into future research + drafting — it is not a one-way pipeline.

A common mistake in this step: classifying everything as "Create". FCC is not a document-production factory; it is a deliberated cycle where Find feeds Create feeds Critique feeds Find again. If your inventory is 95% Create you either have no research surface (Find deficit) or no review surface (Critique deficit). Either is a gap worth fixing during the retrofit.

Step 4 — Quality-gate selection¶

The PHOENIX 58-gate registry (vendored at src/fcc/data/governance/ since v1.3.8) is the canonical source of quality gates. Gates are grouped by tier:

Tier 1 — mandatory. Must pass before a doc merges.
Tier 2 — recommended. Failure triggers review, not block.
Tier 3 — informational. Surfaces a signal; human decides.

A typical docs retrofit selects 8–15 Tier-1 gates + 5–10 Tier-2 gates. Over-gating is as bad as under-gating — a gate that fires on 40% of changes loses its signal.

List gates from the registry:

fcc audit gates --list
# or with JSON output for scripting
fcc audit gates --list --format json | jq '.[] | {id, tier, description}'

For the restructure itself, enforce at minimum:

A Tier-1 completeness gate for each R.I.S.C.E.A.R. component.
A Tier-1 cross-reference integrity gate (no broken persona IDs).
A Tier-2 audience-tier consistency gate (page claims audience: beginner → reading-level check).
A Tier-2 Zachman-cell presence gate.

The fcc audit personas --strict CLI (shipped in v1.5.1) is the machine-readable gate check and is how CI will enforce what you select.

Step 5 — Cross-reference scaffolding¶

Once every author has a persona and every doc has a phase, wire the personas into each other. The authoritative file is src/fcc/data/personas/cross_reference.yaml:

# Abridged example from FCC's own file
entries:
  - persona_id: CMW
    upstream:
      - persona_id: OSC
        reason: "OSC curates FAIR inputs that CMW consumes."
    downstream:
      - persona_id: TLDR
        reason: "TLDR summarises CMW's long-form chapters."
    peers:
      - persona_id: VDS
        reason: "Co-authors diagrams + figures."
    by_type:
      reviewer:
        - PHV
      approver:
        - DAR

Every cross-reference has exactly four relationship types — upstream, downstream, peers, by_type — and every entry has a human-readable reason. The reason is not decoration; forensic auditors rely on it during governance reviews, and the v1.5.1 fcc audit personas --strict gate checks that every entry has one.

For your retrofit, do this in two passes:

First pass — write it yourself. For each persona in your mapping, list who feeds you and whom you feed. Write the reasons.
Second pass — let the audit harness complain. Run fcc audit personas --strict. It will list missing cross-refs, missing reasons, and ID collisions. Fix until zero findings.

A common pitfall here is ID collision with FCC's own persona catalog. If you are adding a custom persona, avoid bare two-letter IDs — use a project-prefix (e.g. ACME_ARCH for an ACME-project architect). The audit will catch collisions, but prevention is cheaper than cure.

Step 6 — Publication-pipeline adoption¶

FCC publishes through a Quarto + Pandoc + Typst pipeline documented in publications/_quarto.yml. To put your docs through the same pipeline:

Add your top-level docs dir to the Quarto book config:

# publications/_quarto.yml
book:
  chapters:
    - index.qmd
    - part: "Your Project"
      chapters:
        - ../docs/your-project/overview.md
        - ../docs/your-project/architecture.md

Render Mermaid diagrams via make pub-diagrams (shipped in v1.3.2, extended in v1.5.2 as make pub-diagrams-v15). The pipeline pre-renders each block to SVG + PNG and rewrites the embed so DOCX / EPUB / PDF formats get real images:
```
make pub-diagrams           # render all diagrams in docs/
make pub-diagrams-v15       # v1.5.0-aligned diagram subset only
```
Author diagrams with explicit figure captions. Since v1.3.5.2 FCC uses a Figure N: caption convention inline with Mermaid blocks for cross-format stability. Do the same in your docs.
Build everything via make pub-all (27+ artifacts across 4 book formats + executive + academic + reference cards + presentations).

Your existing Sphinx or MkDocs build keeps working — the Quarto pipeline is additive, not a replacement. MkDocs stays as the live site; Quarto produces the book artifacts.

Step 7 — Audience-tier cascade¶

The final structural move is to rehome every doc under one of the audience-tier directories:

docs/for-beginners/ — concepts, glossary, first-tutorial pages.
docs/for-professionals/ — day-to-day how-tos, API references.
docs/for-auditors/ — compliance-ready R.I.S.C.E.A.R. completeness checks, quality-gate evidence, trace artifacts.
docs/for-knowledge-engineers/ — ontology + KG patterns, serializer choices.
docs/for-data-architects/ — schema work, object-model design.
docs/for-scientists/ — research-method pages, reproducibility manifests.
docs/for-educators/ — learning-objective pages, assessment rubrics.

Every page in the cascade has three required sections:

What to read first — 1–2 paragraphs oriented for this audience.
Body — the substantive content.
See also for other audiences — 3–5 cross-links to the sibling pages in other tiers covering the same topic.

This last section is what gives the cascade its value. A beginner encountering a page and needing the professional's depth can follow the cross-link; an auditor reading the professional's page and needing the evidence sees the auditor cross-link.

The cascade is not a multiply-by-seven problem. Most topics need 2–3 audience pages, not all 7. Use the tutorial matrix (generated in v1.5.3) as a reference for which audiences typically co-occur.

Working example — retrofitting a single chapter¶

Before the big retrofit, rehearse the workflow on one chapter. Pick a representative doc — not the easiest, not the hardest — and walk it through Steps 2–7 in miniature.

Starting artifact. docs/guides/payments-onboarding.md — a 1,200-word guide that has been in the repo for three years and reads a bit tired.

Step 2 — persona mapping. The original author is a Platform Engineer who maintains the payments integration. In FCC vocabulary that maps most closely to a combination of:

RC (Research Crafter, Find phase) — for the onboarding-prerequisites research surface.
CC (Content Crafter, Create phase) — for the step-by-step guide body.
QC (Quality Crafter, Critique phase) — for the post-onboarding verification section.

The current reviewer is a Security Engineer who maps to PHV (Privacy Handoff Validator). That reveals a gap: the current doc has no explicit reviewer section pointing at PHV — a common drift smell.

Step 3 — workflow-graph extraction. Walking the doc end-to-end, you see three implicit phases:

Prerequisites section (lines 1–40) — Find phase.
Onboarding steps section (lines 41–140) — Create phase.
Verification checklist section (lines 141–180) — Critique phase.

Wire these into the FCC extended-20 graph by inserting explicit phase headers:

<!-- phase: find, persona: RC -->
## Prerequisites

<!-- phase: create, persona: CC -->
## Onboarding steps

<!-- phase: critique, persona: QC, reviewer: PHV -->
## Verification

These HTML comments are machine-readable — the v1.5.1 fcc audit personas --strict gate parses them for audit evidence.

Step 4 — gate selection. For a payments-onboarding doc, three PHOENIX gates are load-bearing:

QG-PRIV-03 (privacy-handoff completeness) — Tier 1.
QG-DOC-01 (R.I.S.C.E.A.R. completeness) — Tier 1.
QG-DOC-04 (cross-reference integrity) — Tier 1.

Optional Tier-2 gates: QG-DOC-08 (reading-level match for declared audience), QG-DOC-11 (Zachman-cell presence).

Step 5 — cross-refs. The new entry in cross_reference.yaml (scoped with the ACME project prefix):

- persona_id: ACME_PAYMENTS_ENGINEER
  upstream:
    - persona_id: RC
      reason: "RC supplies the research surface the engineer synthesises."
  downstream:
    - persona_id: PHV
      reason: "PHV validates the privacy-handoff section of the final doc."
  peers:
    - persona_id: CC
      reason: "CC co-authors the onboarding narrative."

Step 6 — publication-pipeline wiring. Add the chapter to publications/_quarto.yml:

book:
  chapters:
    - part: "ACME payments"
      chapters:
        - ../docs/guides/payments-onboarding.md

Run make pub-diagrams to render the chapter's three Mermaid sequence diagrams to SVG + PNG. Confirm the DOCX + EPUB + PDF outputs embed the images correctly.

Step 7 — cascade rehoming. Split the doc by audience:

docs/for-beginners/payments-onboarding-overview.md — a 400-word orientation + single happy-path example.
docs/for-professionals/payments-onboarding.md — the original chapter, moved + retitled.
docs/for-auditors/payments-onboarding-evidence.md — a 300-word evidence page linking to gate outputs + trace artifacts.

Every page in the cascade cross-links to its siblings.

Total wall-clock time on this single-chapter rehearsal: 3 hours for someone doing it for the first time, 45 minutes once the team has muscle memory. Do this rehearsal before Step 1 of the main retrofit; the lessons are cheap and transferable.

Example — retrofit of a 142-page docs tree¶

A medium project with 142 Markdown files went through this retrofit in 2026-Q1. Their breakdown was:

Inventory (Step 1): 142 files, 67 labelled "professional" after honest audience classification (the initial guess of 130 was a drift smell). 14 beginner, 18 auditor, 23 knowledge-engineer, 12 data-architect, 8 scientist.
Persona map (Step 2): 18 distinct FCC personas covered every author + reviewer. Three custom personas added with the project-prefix convention.
Phase assignment (Step 3): 47 Find, 68 Create, 27 Critique — reasonable balance.
Gates (Step 4): 11 Tier-1 + 7 Tier-2 selected.
Cross-refs (Step 5): 2 passes, 14 findings in the first audit, zero in the second.
Pipeline (Step 6): 6 hours including Mermaid render debugging.
Cascade (Step 7): 48 pages touched two tiers; 12 pages touched three; the rest stayed single-audience.

Total elapsed wall-clock time: 5 days across a 4-person docs team.

Ongoing maintenance after the retrofit¶

A retrofit is a one-off effort; keeping the result healthy is continuous. Three practices keep the discipline sharp:

Pre-merge gate. fcc audit personas --strict runs on every PR that touches docs/ or persona YAML. Any new doc must declare its phase: + audience: + persona: front-matter keys.
Quarterly drift audit. Once per quarter, rerun the full inventory script (Step 1) + compare the disposition against the previous quarter's inventory. Drift between audience tiers is the earliest signal of a docs-team-coordination problem.
Persona-catalog hygiene. When FCC releases a new version, rerun registry.by_category() and compare against your project-local persona mappings. If FCC adds a persona that now fits one of your custom personas better than your custom persona does, deprecate the custom one with a rename pointer.

These practices are cheap + compound over time. The alternative — letting the cascade drift for two years + running another massive retrofit — is the expensive version of the same work.

Checklist for "done"¶

Common pitfalls¶

Vocabulary drift. Your team has words; FCC has words; they are not the same words. "Reviewer" in your team may map to "Approver" in FCC terminology. Build a vocabulary translation table on day one — it is the smallest, most valuable artifact of the whole retrofit.

ID collisions. Two-letter persona IDs collide easily. Use PROJECT_ROLE prefixes for custom personas. The v1.5.1 fcc audit personas --strict gate is fast + catches collisions deterministically.

Missing dimensions. Each persona has a 56-dimension profile (v1.5.1 backfilled the 26 missing profiles for existing personas). If you add a custom persona, generate its dimensions profile via scripts/backfill_dimension_profiles.py so auditors see complete data.

Over-gating. Selecting 25+ gates for a docs retrofit produces false-positive fatigue. Select the minimum set that fires on 5–15% of changes and add more as you learn.

Phase-assignment inflation. Labelling 90% of docs "Create" is the single most common drift smell. Every mature docs tree has Find debt (under-documented research surface) and Critique debt (under-documented review surface). The retrofit is your chance to close both.

Cascade sprawl. You do not need a page in every audience tier for every topic. Most topics need 2–3; some need 1. Use the tutorial matrix to see what cascades typically look like in FCC's own docs.

Next steps¶

Integrating FCC into a mature codebase — wire the retrofit into CI/CD.
Adopting universal services — when your retrofit needs cross-ecosystem coordination.
ADR-010 Six pillars architecture — the design context for v1.5.0.
Codename decoder — reference for every codename you will encounter during the retrofit.
PHOENIX 58-gate registry — authoritative gate list.
Custom personas tutorial — when the retrofit requires new persona shapes.