Skip to content

Model-Driven Documentation

Purpose

UC-BoK adopts a model-driven documentation approach.

The catalogs/ directory is the machine-readable source of truth for all business knowledge. The docs/ directory is the human-readable publication layer — generated from or informed by YAML catalogs.

Catalog Sources (v1.2.0-alpha)

Catalog Path Entries
Domains catalogs/domains.yaml 8
Capabilities catalogs/capabilities.yaml 25
Services catalogs/services.yaml 60+
Events catalogs/events.yaml 107
Processes catalogs/processes.yaml 15
Applications catalogs/applications.yaml 13
Business Objects catalogs/business-objects/*.yaml 46
Patterns catalogs/patterns.yaml 7
Reference Architectures catalogs/reference-architectures/*.yaml 3
Experience catalogs/experience/*.yaml actors, journeys, tasks
Assessment Profiles catalogs/assessment-profiles/*.yaml 1
Vendor Mapping catalogs/vendor-mapping.yaml 0 (ADR-017)

Legacy

catalogs/legacy/ contains pre-v0.5 monolithic YAML files. They are read-only and will be removed once migration is complete.

Generation Pipeline

catalogs/*.yaml
      ↓
scripts/generate_catalog_pages.py
      ↓
docs/generated/catalogs/*.md
docs/generated/catalogs/processes/*.md
      ↓
MkDocs site (site/)

Run make generate to regenerate all catalog pages from YAML.

Warning

Never edit files under docs/generated/ manually. They are overwritten by make generate.

Governance Rules

  1. Model First — add stable id to model elements before writing Markdown.
  2. Ontology Before Catalog — each concept type requires a normative spec in specifications/.
  3. Cross-reference by ID — use stable id values, never display names.
  4. Classification Required — every catalog entry must carry classification.
  5. Validation before commit — run make check to validate all catalogs.

References

  • catalogs/ — canonical YAML source models
  • scripts/generate_catalog_pages.py — primary catalog page generator
  • scripts/generate_docs.py — legacy generator (deprecated)
  • UCBOK-004 — Source Model Governance