FCC for Technical Writers¶

Welcome, technical writer. This track is written for documentation professionals — staff technical writers, freelance doc consultants, content strategists, DX (developer experience) writers, and content-ops folks — who want to adopt FCC patterns for structured, persona-driven, diagram-rich documentation.

FCC's documentation philosophy and infrastructure are unusually mature for an OSS project its size. It combines hand-authored narrative with generated reference material; it treats Mermaid diagrams as first-class content; it uses the R.I.S.C.E.A.R. specification as a contract for role-based docs; and it publishes simultaneously to web, PDF, EPUB, DOCX, and slides via a single source.

What you will learn¶

A concrete Mermaid-diagram convention that produces publication-grade output across web, PDF, and EPUB.
How to drive documentation from persona YAML files so that role descriptions stay current.
A publication pipeline pattern (Quarto + Pandoc + Typst) that scales from blog post to book.
Glossary-governance techniques for multi-audience, multi-format documentation.

How this track is organized¶

Page	Focus	Effort
Getting Started	Orientation; tool survey	30 min
Mermaid Conventions	Figure naming, captions, rendering	1 hour
Persona-Driven Docs	YAML → Markdown pipeline	2-3 hours
Publication Pipeline 101	Multi-format publishing	3-4 hours
Glossary Governance	Terminology discipline	1-2 hours
Further Reading	References and tools	reference

Prerequisites¶

Comfort with Markdown.
Familiarity with Git (commits, branches, pull requests).
Experience with at least one docs pipeline (MkDocs, Docusaurus, Hugo, Read the Docs, etc.).
Willingness to edit YAML.

You do not need:

To write Python (but you will read some).
Extensive LaTeX experience (Quarto hides most of it).
Prior AI or ML background.

Why FCC is worth studying¶

Three things FCC does well:

Diagrams as code. ~280 Mermaid blocks across the docs, rendered to SVG + PNG for HTML and PDF respectively, via a Pandoc Lua filter. Diffable in PRs. Reproducible.
Generated reference docs. 173 model cards auto-generated from persona YAMLs. Zero drift between code and docs.
Multi-format output. One source tree produces a website, a 4-book series, executive briefings, academic papers, and reference cards via a single make pub-all.

Each of these patterns is individually adoptable. You do not have to adopt all three to get value.

What you will not learn here¶

Copy-editing. There are better resources.
SEO or content-marketing strategy. Off-topic.
Structured-content standards (DITA, DocBook). FCC chose Markdown-plus-YAML instead; you will not find DITA tooling here.
Headless-CMS patterns. Different architecture.

A note on audience overlap¶

This track's neighbors in docs/tutorials/ include:

for-open-source-maintainers — you will find useful material there on docs-as-code-patterns.md and release-cadence-lessons.md.
for-students — if you write educational content, assignment-patterns translates to tutorial structure.
for-policy-makers — if your users include policy audiences, the ecosystem-glossary is a model of plain-language definitions.

Feel free to dip in; the tracks are independent but complementary.

The 15-minute orientation¶

Before you dive into this track's pages, spend 15 minutes browsing the FCC repo itself. Look at:

docs/index.md — the root entry point.
docs/decisions/ — the 5 ADRs.
docs/model-cards/ — one auto-generated card.
docs/guidebook/ — one chapter.
publications/ — the publishing directory.
src/fcc/templates/docs/ — the Jinja templates that generate the reference docs.

You will notice the separation between narrative (hand-authored) and reference (generated). That separation is the heart of the pattern.

Starter mental model¶

Think of FCC's docs as having three layers:

Source layer: YAML personas, JSON scenarios, hand-authored Markdown narrative.
Generation layer: Jinja templates + Pandoc + Quarto, which turn source into publishable Markdown.
Rendering layer: MkDocs, Pandoc, Typst, producing web, PDF, EPUB, DOCX, PPTX.

Your job as an adopting writer is usually in the narrative source + the generation templates. You rarely touch rendering.

Where next¶

If you want to see quick wins, start with Mermaid Conventions — it is the lowest-friction pattern and most visible to readers. If your pain is docs drift, go to Persona-Driven Docs. If you need end-to-end understanding before adopting anything, Getting Started.