Skip to content

Docs ART

Focus: FCC Guidebook (24 chapters, 10 labs), 3-book series (30 chapters), 23 Jupyter notebooks, 27 Streamlit apps, 19+ guided demos, 173 auto-generated model cards, MkDocs site, multi-format publishing pipeline (Quarto + Pandoc + Typst). PI cadence: 10-week Program Increment with five 2-week iterations inside; last iteration is the Innovation & Planning (IP) iteration for PI close + system demo. Value streams served: Documentation (primary), Delegation (contributor docs, patent docs).

Team topology (Skelton & Pais)

The Docs ART is a virtual team inside the FCC authority repo, with contributors across many personas. Using Skelton & Pais topology vocabulary:

  • Authoring team — Stream-aligned team owned by Documentation Evangelist (DE). Owns the MkDocs site config, the 10+ audience trees (decision-makers, architects, developers, auditors, educators, knowledge engineers, operators, scientists, data-architects, professionals), the Guidebook chapters, the 3-book series chapters, and the guided-demo registry. The stream is the continuous flow of docs matching code changes; every Framework + Ecosystem ART PR tagged with a docs impact flag feeds this stream.
  • Reconciliation team — Enabling team owned by Three-Layer Doc Reconciler (TLDR). Enforces the ROADMAP.md / STRATEGIC_ARCHITECTURE_REVIEW.md / AGENTS.md three-layer convention across every ecosystem project. Publishes the ecosystem-wide drift heatmap. Treated as an enabling team because its role is to remove friction from Authoring + Narrative teams and the Ecosystem ART's constellation maintainers.
  • Publication team — Platform team owned by Executive Communicator (EC). Owns the multi-format publishing pipeline (publications/ tree), Quarto profiles (combined, executive, academic, patent), Pandoc defaults, and the PDF/EPUB/DOCX/HTML artifact set under publications/_output/. Provides publishing as a platform that every other team consumes when they need a press-ready artifact.
  • Narrative team — Complicated-Subsystem team owned by Semantic Taxonomy Engineer (STE). Keeps the glossary, cross-reference matrix, persona interaction guides, and the archetype atlas canonical. Treated as a complicated subsystem because the 147-persona cross-reference matrix + 37 archetypes + persona interaction guide demand specialist knowledge of the whole catalogue at once.
  • Open-science curation team (shared) — Enabling team served by Open-Science Curator (OSCU), the 114th persona landing in v1.4.4. OSCU owns the 12 OPEN-SCI templates and ensures every new persona, artifact, or audience tree references at least one OPEN-SCI template in its open_science_refs. OSCU coordinates reproducibility manifests for Research Center paper handoffs (pairs with RHL).

PO / PM / RTE mapping

  • Product Owner (PO) — Executive Communicator (EC). Owns the iteration backlog (publication targets per iteration), prioritizes authoring stories, accepts completed work.
  • Product Manager (PM) — Documentation Evangelist (DE). Owns the PI backlog, authors PI objectives, aligns the Docs ART with portfolio epic PE-003 (i18n).
  • Release Train Engineer (RTE) — Three-Layer Doc Reconciler (TLDR). Facilitates PI planning, iteration reviews, system demos, and Inspect & Adapt. TLDR owns the reconciliation passes that gate doc-release alignment.

Cadence

  • Daily: async via PR reviews and docs-as-code quality-gate CI.
  • Iteration (2 weeks): DE consolidates what landed in Framework + Ecosystem ARTs and produces a docs digest; TLDR runs a reconciliation pass against the 19-project ecosystem inventory; EC rebuilds publications when source trees change.
  • Backlog refinement: mid-iteration, asynchronous. EC drafts publication-slot estimates; DE confirms audience priority; TLDR resolves reconciliation blockers. Roughly 2 hours of PO + PM time per iteration.
  • PI boundary (10 weeks): Docs ART PI scorecard from SMC aggregating Guidebook completeness, audience-tutorial coverage, MkDocs strict-mode build success rate, publication-artifact count, and reconciliation-pass cleanliness.
  • PI cadence aligns with RC's quarterly rhythm — see ../pi-calendar.md.
  • Innovation & Planning (IP) iteration: the final iteration of each PI is the IP iteration — reduced new-content authoring, higher refactoring + regeneration density, audience-feedback absorption.

Backlog (PI-2026-Q3)

Populated at PI planning on 2026-06-30. Initial candidates:

  • Publish this docs/safe/ tree into the MkDocs nav (handled at v1.4.1 integration by the coordinating agent).
  • Author the SAFe-operating-model audience tutorial for docs/for-teams/ (or its v1.3.10-era successor).
  • Grow the guided-demo registry with a SAFe-instance walkthrough demo (after v1.4.1 ships).
  • Advance PE-003 (i18n) readiness: inventory Guidebook chapters for locale-template eligibility.
  • Maintain ROADMAP/SAR/AGENTS three-layer cleanliness across all 10 constellations and 4 JV partners.
  • Regenerate the 173 model cards as persona set expands.
  • Extend the Quarto patent profile to cover the v1.5.0 patent-delegation epic (PE-007).

Metrics signals

SAFe Metrics Crafter (SMC) aggregates these signals into the Docs ART PI scorecard:

  • MkDocs strict-mode build pass rate.
  • Publication pipeline artifact count (currently 27 PDFs/EPUBs/DOCX/HTML outputs, target: grow with coverage).
  • Guidebook chapter + lab completeness (currently 24 chapters, 10 labs).
  • Model-card count (currently 173: 147 personas + 6 workflows + 20 categories).
  • Demo registry size (currently 19+).
  • Three-layer reconciliation cleanliness per constellation.
  • Audience-tutorial completeness across the 10+ audience trees.

Collaboration with sibling ARTs

  • Framework ART tags PRs with docs-impact flags so DE can batch doc updates.
  • Ecosystem ART changes to plugin contracts force plugin-cookbook updates.
  • Three-Layer Doc Reconciler (TLDR) feeds Forensic Auditor (FA) with reconciliation findings for ecosystem-wide evidence graphs.
  • SAFe-FCC Bridge Interpreter (SFBI) feeds TLDR with translation hints so reconciliation uses canonical vocabulary.
  • Open-Science Curator (OSCU) supplies OPEN-SCI template references that DE weaves into new audience trees.

Quality gates

  • QG-DOC-001 — MkDocs strict-mode build success.
  • QG-DOC-002 — Publications pipeline success (make pub-all).
  • QG-DOC-003 — Audience-tutorial presence across the 10+ audience trees.
  • QG-DOC-004 — Three-layer reconciliation cleanliness (no P0 findings per project).
  • QG-DOC-005 — Model-card regeneration up-to-date with persona registry.

PI objective template

Same SAFe template as the Framework ART: Specific, Measurable, Actionable, Reasonable, Timed. 3-5 objectives per PI. Predictability band 80-100%. Below 60% triggers an Inspect & Adapt focused on authoring bottlenecks (typically: docs debt accumulated when Framework and Ecosystem ARTs ship faster than DE can absorb).

Doc tree anchors

The Docs ART's canonical working artifacts:

  • docs/guidebook/ — 24-chapter FCC Guidebook.
  • docs/books/ — 3-book series, 30 chapters.
  • docs/for-* — audience-specific tutorial trees.
  • docs/model-cards/ — 173 auto-generated model cards.
  • docs/decisions/ — 5+ Architecture Decision Records (ADRs).
  • docs/safe/ — this tree (SAFe operating model canonical).
  • docs/patent/ — patent-claim infrastructure (PE-007).
  • docs/resources/templates/open-science/ — 12 OPEN-SCI templates curated by OSCU.
  • publications/ — multi-format publishing tree (Quarto + Pandoc + Typst).
  • notebooks/ — 23 Jupyter notebooks.
  • apps/streamlit/ — 27 Streamlit apps.