Skip to content

Getting Started (Technical Writers)

A 30-minute orientation to the FCC documentation system, sized for a writer who is evaluating whether to adopt its patterns.

Clone and walk the tree

git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext

Navigate:

  • docs/ — the web-facing docs. Site generator: MkDocs-material.
  • docs/guidebook/ — the 24-chapter guidebook.
  • docs/books/ — the 3-book series, 30 chapters.
  • docs/decisions/ — 5 ADRs.
  • docs/model-cards/ — 173 generated cards.
  • docs/tutorials/ — audience tracks (this one is inside for-technical-writers/).
  • publications/ — Quarto + Pandoc source for multi-format output.
  • src/fcc/templates/docs/ — 23 Jinja templates.

What to look for:

  • Consistent YAML front matter at the top of every Markdown file.
  • Consistent Mermaid diagram convention with Figure numbering.
  • Clear split between narrative and generated.
  • A Makefile with docs, pub-all, and related targets.
make venv && source .venv/bin/activate
make install-dev    # includes doc deps
pip install mkdocs-material

For the full publication pipeline you also need:

  • Quarto 1.5+ (with bundled Typst)
  • Pandoc (bundled with Quarto)
  • Chromium or Firefox (for Mermaid rendering)

make pub-all exercises everything. Expect first run to take 5-10 minutes.

What each tool does

  • MkDocs-material. Web site generator. Markdown → HTML. Handles navigation, search, theming.
  • Jinja2. Template engine. Renders YAML into Markdown.
  • Pandoc. Universal document converter. Markdown → PDF, EPUB, DOCX.
  • Quarto. Scientific-publishing wrapper. Coordinates Pandoc + Typst + knitr.
  • Typst. Typesetting system. Replaces LaTeX for most use-cases in FCC.
  • Mermaid. Diagram-as-code. Fenced mermaid blocks in Markdown.

You do not need to master all of them on day one. Adopt one layer at a time.

The two-layer pattern

FCC's docs have a sharp line between narrative and generated. Examples:

  • Narrative: guidebook chapters, ADRs, tutorial pages, this page.
  • Generated: model cards, cross-reference matrices, persona evolution guides.

The generated docs carry a comment at the top:

<!-- AUTO-GENERATED. Edit the template at src/fcc/templates/docs/model_card.md.j2 -->

Rule: humans edit narrative. The generator edits generated. PR review enforces this.

Front matter

Every Markdown file begins with YAML front matter:

---
audience: technical-writers
tier: foundational
difficulty: beginner
track: for-technical-writers
version: v1.7.0
---

The keys above are FCC's; use any scheme you like. Important: be consistent. Front matter drives site navigation, audience filtering, version labels, and search facets.

Diagram philosophy

FCC uses Mermaid for roughly 280 diagrams. The conventions (detailed in Mermaid Conventions) are:

  • Every diagram has a Figure number.
  • Every diagram has a caption below, starting with "Figure N:".
  • Every diagram has a short intro paragraph before and a follow-up paragraph after.

The net effect is that readers can skim a page on diagrams alone and understand the structure. The captions double as alt text for accessibility and as anchor points for cross-references.

Cross-reference discipline

FCC cross-links heavily:

  • Inline links between docs.
  • A cross-reference matrix (auto-generated) for personas.
  • Footer "Where next" sections on most narrative pages.

The rule-of-thumb: a narrative page should have 3-10 inbound links and 3-5 outbound. Too few and readers feel lost; too many and pages become indexes.

What you can adopt immediately

Three low-effort wins, each under one hour:

  1. Add YAML front matter to every existing doc page. Even if you do not use it yet, future-you will.
  2. Adopt the "Where next" footer convention. Three links: one deeper, one adjacent, one to reference.
  3. Rename diagrams to follow Figure-N convention. Readers will notice improved navigation.

None of these require new tooling.

What takes a weekend

What takes a sprint

  • Migrate a book-length asset (e.g., a handbook) to FCC-style multi-format publishing. Expect 1-2 weeks of dedicated work the first time, much less on subsequent books.

Tooling opinions

FCC's choices, with its reasoning:

  • Markdown over reStructuredText. Easier for external contributors.
  • MkDocs over Sphinx. Simpler; better defaults.
  • Quarto over raw Pandoc. Higher-level abstraction; bundles Typst.
  • Typst over LaTeX. Faster, clearer errors, better defaults.
  • Mermaid over Graphviz. Diffable; renders in GitHub directly.
  • YAML over TOML. Richer for nested structures.

None of these is dogma. If your project has a strong reason to choose differently (e.g., your org already uses Sphinx), choose differently. The patterns transfer even if the tools differ.

Honest caveats

  • The pipeline is complex. Five tools is more than zero tools. Newcomers sometimes bounce.
  • Mermaid rendering is brittle. Chromium occasionally fails on diagrams with many nodes. See FCC's own cache workaround.
  • Multi-format output takes disk. The full _output/ directory runs ~30 MB for FCC. Commit with care.
  • YAML is picky. Indent errors are inevitable at first.

Reading order

If you have 30 minutes, read this page and skim Mermaid Conventions. If you have 2 hours, add Persona-Driven Docs. If you have a day, read the full track in order.

Where next

Go to Mermaid Conventions for the most visible pattern, or to Persona-Driven Docs if docs drift is your main pain.