Skip to content

Further Reading

Background, tools, and specifications for technical writers adopting FCC docs patterns.

Within this repo

  • docs/decisions/ — all 5 ADRs. Especially ADR-0002 (Persona Schema) and ADR-0004 (Compliance Framework).
  • CLAUDE.md — living project overview.
  • RELEASE_NOTES.md — the cadence history, full of narrative release descriptions. Read for voice.
  • docs/guidebook/ — 24 chapters of hand-authored technical writing. The closest thing FCC has to a style guide by example.
  • docs/books/ — 3 books × 30 chapters. For long-form style.
  • docs/model-cards/ — 173 generated pages. For generated-style.
  • publications/ — the publication pipeline source.
  • src/fcc/templates/docs/ — 23 Jinja templates.
  • src/fcc/scaffold/doc_generator.py — the generator in code.

External — documentation theory

  • Diátaxis (Daniele Procida, diataxis.fr). Four quadrants (tutorial, how-to, reference, explanation) and why they should not be mixed. Foundational.
  • "Docs Like Code" (Anne Gentle). The classic treatment of docs-as-code.
  • "Every Page Is Page One" (Mark Baker). On writing for discoverability.
  • Information Development textbook literature — JoAnn Hackos, "Managing Your Documentation Projects."

External — style guides

  • Microsoft Writing Style Guide. Comprehensive and up to date. Available free online.
  • Google Developer Documentation Style Guide. Shorter; highly readable.
  • Apple Style Guide. Precise; slightly more formal than Google.
  • The Chicago Manual of Style. For long-form books, still the reference.

FCC's in-house voice draws on Google's style guide primarily, with a more narrative tone for tutorials and guidebook chapters.

External — Markdown and lightweight markup

  • CommonMark spec. Know what you are writing against.
  • GitHub Flavored Markdown. Extensions widely supported.
  • MDX (if you use Docusaurus or similar). Markdown with JSX.

External — static site generators

  • MkDocs-material documentation at squidfunk.github.io/mkdocs-material. Rich and regularly updated.
  • Docusaurus. Strong React ecosystem.
  • Hugo. Fastest; sometimes opaque.
  • Zola. Rust-based; minimal.
  • Read the Docs. Hosted MkDocs/Sphinx for projects that want managed hosting.

External — diagramming

  • Mermaid documentation at mermaid.js.org. Regularly updated; read release notes.
  • PlantUML. Different syntax; richer UML; heavier toolchain.
  • draw.io / diagrams.net. GUI-based; exports to PNG/SVG for commit-alongside-Markdown use.
  • Excalidraw. Sketch-quality; widely loved for architecture overviews.

External — Pandoc and Quarto

  • Pandoc documentation at pandoc.org. Long and technical; keep bookmarked.
  • Quarto documentation at quarto.org. Much more user-friendly.
  • Typst docs at typst.app/docs. Short; pleasant.
  • "Writing the Docs" (Spotlight talks). Video archive, full of gold.

External — multi-format publishing

  • "Quarto: An open-source scientific and technical publishing system" — Carpenter et al. 2023.
  • "Bookdown" (Xie). Predecessor to Quarto in R ecosystem; still educational.
  • "Elements of Typographic Style" (Bringhurst). For when your PDF output needs to look right.

External — glossary and controlled vocabulary

  • SKOS (Simple Knowledge Organization System) specification — a W3C standard. FCC uses this for vocabulary serialization.
  • SKOS-XL for labels. When you need multi-lingual terms.
  • ISO 25964 (thesauri and interoperability). For larger organizations with controlled-vocabulary needs.
  • The Getty Vocabularies. Real-world, scale-hardened examples.

External — accessibility

  • WCAG 2.1 AA — baseline accessibility target.
  • "A Web for Everyone" (Horton & Quesenbery). Short; impactful.
  • The A11y Project checklist.
  • "Inclusive Components" (Heydon Pickering). Shorter, practical.

Technical writing that ignores accessibility is technical writing missing a large fraction of its audience.

External — internationalization

  • GNU gettext conventions. Not the only i18n approach, but the most portable.
  • ICU MessageFormat. Richer pluralization and gender handling.
  • "The A-Z of Localization" (various). Short reads are plentiful.

FCC's v1.6 seed translations (FR, ES, DE) were driven by a simple locale-file pattern.

Tools and utilities

  • Vale — prose linter. Rules as YAML. Can enforce style guides.
  • Markdownlint — structural Markdown linting.
  • Textlint — pluggable prose linter.
  • Pre-commit — hook manager.
  • Typos — spell-checker that does not falsely flag code identifiers.
  • Alex — checks inclusive language.

Pick two or three; do not adopt all. Linter fatigue is real.

Reading order

For a tech writer new to FCC patterns:

  1. This page's companion: FCC Getting Started. (30 min.)
  2. One ADR. (30 min.)
  3. Diátaxis site. (90 min.)
  4. Microsoft Writing Style Guide, scanning. (60 min.)
  5. This page's companion: Mermaid Conventions and Persona-Driven Docs. (2 hours combined.)

After that, jump into a real adoption on your own docs.

Community

  • Write the Docs — the vibrant global community. Slack, conferences, meetups.
  • MDN Content — exemplary community-driven docs.
  • Read the Docs community — active forum.
  • GitHub Discussions on FCC's repo — feel free to post questions with the docs tag.

What to bookmark

  • diataxis.fr
  • developers.google.com/style
  • quarto.org
  • mkdocs.org
  • mermaid.js.org
  • writethedocs.org

Where next

Return to the track index to finish your reading plan, or begin adopting patterns in your own docs. The shortest path to visible impact: adopt Mermaid Conventions this week, Persona-Driven Docs next week, and leave Publication Pipeline 101 for a later sprint.