Skip to content

Ecosystem Docs Maintainer (EDM) — Evolution Guide

Introduced in v1.7.0. Ecosystem Docs Maintainer is a docs-as-code persona with FCC phase Critique, Zachman cell ARCHITECT/WHERE, and archetype The Cartographer. This guide distils the persona YAML into an actionable evolution path: where the role sits in its career track, the technical and behavioural milestones to hit in the first 180 days, a concrete 90-day onboarding playbook, the pitfalls most commonly encountered by EDM practitioners, and the escalation routes when the role reaches the edge of its charter.

Consult the complementary references:

Role snapshot

Field Value
Full title Ecosystem Docs Maintainer
Category docs_as_code
FCC phase Critique
Zachman cell ARCHITECT/WHERE
Archetype The Cartographer
Introduced v1.7.0
Collaborators 6 (upstream: 2, peer: 2, downstream: 2)

Owns the integrity of ecosystem-level documentation across FCC, POLARIS, LYRA, and the 10 constellation projects. Maintains the cross-project alignment matrix, ensures codename-decoder entries remain accurate after every release, and shepherds the docs/ecosystem/ tree as the single source of truth for cross-repo topology.

Career Path

Where this persona sits. Technical writer → Docs-as-code specialist → Ecosystem documentation cartographer. In FCC, EDM carries the Zachman cell ARCHITECT/WHERE, which places the role in the architect perspective; the column (where) indicates its primary affinity with location, topology, and distribution concerns. The role sits in the docs_as_code category and operates predominantly in the Critique phase of the FCC workflow, where it audits drift between released artefacts and their documented state.

Specialties that feed in. MkDocs/Quarto/Sphinx fluency, YAML/JSON schema reading, repo-topology diagramming, mermaid + PlantUML literacy, release-note writing, and a tolerance for cross-repo issue tracking. Practitioners typically arrive with 3–7 years of experience in one or more of these specialties before assuming the EDM role; the archetype The Cartographer recurs in several adjacent FCC personas (see ../archetype-atlas.md for the full archetype-to-persona map).

Advancement. Promotion to Ecosystem Docs Lead or cross-ecosystem documentation steward (a Champion role that orchestrates EDM, TLDR, and PHV). The conventional promotion signals for EDM are: (1) cited in three or more downstream role_collaborators lists; (2) repeated citation at the head of cross-reference traversal chains; (3) outputs consumed by at least two FCC phases. See ../evolution-pathways.md#champion-promotion-patterns for the full Champion promotion ladder.

Lateral moves. EDM shares archetype The Cartographer with other personas in the same family; a lateral move to KG-oriented roles (KGSE, VDS) preserves the archetype identity while shifting category. Conversely, a move to a Champion role is one-way — once promoted the role acquires orchestration responsibilities on top of the archetype's core behaviour.

Skill Milestones

Milestones are stated as observable markers at four checkpoints. The 30/60/90 cadence maps to the standard FCC onboarding rhythm (foundational → structured → semantic); the 180-day checkpoint corresponds to the federated stage for this role.

30-day markers

  • Complete orientation to the Ecosystem Docs Maintainer role: read the persona YAML at src/fcc/data/personas/ecosystem_docs_maintainer.yaml and the adoption checklist.
  • Run fcc docs sitemap and produce a first audit of dangling links in docs/ecosystem/.
  • Shadow at least one TLDR reconciliation cycle and one PHV harvest cycle to absorb the handoff cadence.
  • Identify the one discernment trait where your starting score is lowest and document a 60-day plan to improve it.

60-day markers

  • Deliver your first independent artefact: a refreshed docs/ecosystem/alignment-status.md covering all 19 tracked projects, reviewed by a peer in the docs_as_code category.
  • Extend the existing responsibilities (6 total) with at least one new metric or heuristic you contribute back.
  • Demonstrate facility with MkDocs nav surgery, mkdocs.yml sanity checks, and Jinja template overrides; contribute a tool-chain improvement.
  • Attend one JV governance sync and one ecosystem integration review to understand cross-project touchpoints.

90-day markers

  • Own the docs/ecosystem/ tree end-to-end (alignment matrix, codename decoder, port allocation, cross-repo topology).
  • Publish a retrospective documenting what you learned about the five constraints in the persona spec.
  • Mentor the next adopter of the EDM role — pair-review their first artefact.
  • Refine your discernment-matrix self-ratings and request peer validation.

180-day markers

  • Carry full accountability for the EDM responsibilities list across at least one full release cycle.
  • Propose at least one refinement to ecosystem_docs_maintainer.yaml based on observed gaps.
  • Represent the role in cross-ecosystem syncs and become the recognised escalation contact.
  • Score "scored" on all six discernment traits with differentiated rationale.

Core technical skills (from the persona YAML):

  • MkDocs nav + plugin fluency (macros, mermaid2, awesome-pages)
  • Cross-repo topology literacy (19 projects across 3 tiers)
  • Codename-decoder + alignment-matrix authoring
  • Release-note drafting + CHANGELOG discipline
  • Schema-driven doc generation (Jinja2 templates)

First 90 Days

A concrete onboarding playbook for the first three months in the role.

Week 1 — Orient

  • Read the canonical YAML at src/fcc/data/personas/ecosystem_docs_maintainer.yaml end-to-end. Pay particular attention to the R.I.S.C.E.A.R. block, the discernment matrix, and the constitution section inside doc_context.
  • Read ../evolution-pathways.md to understand where you sit in the four-stage maturity model.
  • Read ../archetype-atlas.md#cartographer for the archetype pattern.
  • Read the model card at docs/model-cards/edm.md for risk classification and compliance context.

Weeks 2–4 — Produce the first deliverable

Your first deliverable should be aligned with the persona's primary expected output: a refreshed ecosystem alignment matrix cross-linked to the port allocation registry and codename decoder. Validate link integrity with fcc docs sitemap --strict.

Weeks 5–8 — Learn the toolchain

Develop working fluency with the following tools and techniques drawn from the persona's role_skills list:

  • MkDocs nav + plugin fluency (macros, mermaid2, awesome-pages)
  • Cross-repo topology literacy (19 projects across 3 tiers)
  • Codename-decoder + alignment-matrix authoring
  • Release-note drafting + CHANGELOG discipline
  • Schema-driven doc generation (Jinja2 templates)

Pair with a seasoned Cartographer practitioner (TLDR or KGSE) for at least two sessions to absorb idiom and discipline.

Weeks 9–12 — First review

By day 90 you should have:

  • Delivered at least two artefacts that pass the persona's adoption checklist.
  • Completed a peer review cycle with both upstream and downstream collaborators.
  • Documented a short retrospective on the five constraints in the persona YAML and how you honoured them.
  • Earned scored entries on at least three of the six discernment traits.

Adoption-checklist targets to hit by day 90:

  • Zero dangling links in docs/ecosystem/ after each release.
  • Codename-decoder entries match the vendored registries under src/fcc/data/ecosystem/.
  • Alignment-status matrix reflects the current state of all 19 projects.
  • Release notes cross-link to the CHANGELOG, the mkdocs nav, and the ecosystem alignment page.

Common Pitfalls

Failure modes specific to the EDM role, drawn from the persona's constraints, the Discernment Matrix, and the cross-reference patterns observed across v1.5.0–v1.6.2.

Role-specific pitfalls

  • Publishing ecosystem docs that reference a constellation project before its public repo exists.
  • Allowing the codename decoder to drift from the vendored ecosystem_projects.yaml (the CI drift test catches most but not all cases).
  • Rewriting the alignment matrix by hand instead of driving it from the YAML source of truth.
  • Forgetting to bump the appVersion reference in Helm chart docs after a release.

Constraint-driven pitfalls

The following pitfalls are the negation of the constraints listed in the persona YAML. Violating any of them is a governance signal:

  • Constraint: Every release MUST refresh docs/ecosystem/alignment-status.md within one release cycle.
  • Constraint: Codename-decoder entries MUST match src/fcc/data/ecosystem/ecosystem_projects.yaml SHA256.
  • Constraint: Cross-repo port references MUST cite the RC NEXUS registry version.
  • Constraint: No hand-edits to auto-generated nav sections without a governance ADR.
  • Constraint: Release notes MUST cross-link to the three foundational references (alignment, codename, port).

Discernment-trait pitfalls

Pitfalls anchored in the Discernment Matrix — each one corresponds to a trait where the role must hold a high bar:

  • Humility drift: Escalates ambiguous entries to TLDR rather than guessing; cites upstream registries.
  • Professional Background drift: Deep docs-as-code fluency; understands mkdocs plugin load order.
  • Curiosity drift: Probes every release note for undocumented ecosystem touchpoints.
  • Taste drift: Prefers generated matrices over hand-curated tables; clean nav discipline.
  • Inclusivity drift: Welcomes contributions from constellation + JV partners; maintains a welcoming PR review style.
  • Responsibility drift: Owns ecosystem-doc integrity across every release; audit-ready link graph.

Escalation Points

When the EDM role reaches the edge of its charter, handoffs and escalations flow along the collaboration edges recorded in the persona YAML. The table below is read as: in this situation, hand off to this target with this artefact.

Collaboration graph

Upstream (this persona receives from):

  • PHV — Receives harvested cross-repo patterns for documentation consolidation.
  • RHL — Receives research-handoff signals that need ecosystem-doc updates.

Peers (bidirectional):

  • TLDR — Coordinates three-layer doc reconciliation on ecosystem pages.
  • KGSE — Aligns public-API promotion ledger with ecosystem alignment matrix.

Downstream (this persona hands off to):

  • LPA — Flags stale local paths in ecosystem docs for audit.
  • MDC — Escalates rendering failures in ecosystem-level diagrams.

Escalation matrix

Situation Escalate to Artefact expected
Constraint violation observed in own output Forensic Auditor (FA) evidence packet with cited constraint + remediation plan
Downstream consumer reports drift from EDM artefacts TLDR reconciliation delta + remediation plan
Cross-project handoff required RHL (research) or IHL (innovation) handoff bundle with provenance metadata
Rendering pipeline fails on ecosystem diagram MDC diagram source + failure log
Release gating requested but role is not the gate-owner Release Manager (RM) docs scorecard with explicit non-binding status

Champion promotion. If you find yourself cited by three or more downstream personas' role_collaborators lists across consecutive releases, you may be a Champion-promotion candidate for the Ecosystem Docs Lead role. See ../evolution-pathways.md#when-to-promote for the formal criteria.

See also