Skip to content

ADR-018 — UC-BoK Editorial Publishing Platform (ED-001)

Status

Accepted

Context

UC-BoK v1.1-alpha has reached architectural completeness. The knowledge model is stable: 17 specifications, 17 ADRs, 3 Reference Architectures, 25 capabilities, 15 processes, 819 Knowledge Graph nodes, and a validated UCMI Assessment Engine.

The documentation site (MkDocs + Material) serves as the primary consultation interface. A PDF export has existed since early versions but was generated as a raw documentation dump — not as an intentional editorial product.

At this maturity level, UC-BoK has four distinct products:

  1. Repository — canonical knowledge source for architects and contributors
  2. Knowledge Graph — machine-queryable model for tooling and automation
  3. Documentation Site — web consultation layer for practitioners
  4. Book — distributable editorial artifact for broad dissemination

The fourth product does not yet exist in professional form. The current PDF is an export, not a book.

The distinction matters: the book is not an export of the documentation — the documentation is one projection of the knowledge, and the book is another.

Decision

UC-BoK will define an Editorial Publishing Platform (milestone ED-001) before implementing any PDF layout or CSS.

ED-001 is a design milestone, not an implementation milestone. Its output is a complete Editorial Design System that defines the visual and structural identity of the UC-BoK Book before a single line of CSS is written.

This mirrors the same discipline applied to the knowledge model itself: - first the ontology, then the schemas, then the catalogs - here: first the design system, then the layout, then the pipeline, then the CSS

Editorial Design System — ED-001 Scope

1. Editorial Identity

  • Cover system (title, subtitle, version, edition)
  • Title pages and copyright page
  • Editioning and versioning conventions
  • Colophon

2. Typography

  • Body font, heading font, monospace font
  • Spacing scale and typographic hierarchy
  • Line length, leading, paragraph rhythm

3. Editorial Components

Stable visual identity for each UC-BoK content type: - Specification · ADR · Reference Architecture · Pattern - Capability · Business Object · Process · Example - Warning · Decision · Comparison

4. Chapter Architecture

  • Chapter opener and section opener templates
  • Running headers and footers
  • Page numbering scheme
  • Table, figure, and diagram conventions
  • Glossary and annex layouts

5. Visual Grammar

  • Iconography and color palette
  • Callout types and semantic boxes
  • Caption conventions
  • Code block and diagram framing

6. Publishing Pipeline

Markdown
  ↓
MkDocs (docs site — unaffected)
  ↓
Book HTML (separate build target)
  ↓
Print Layout (WeasyPrint or Paged.js)
  ↓
PDF
  ↓
Release Artifact
The pipeline must not interfere with the normal documentation site build.

7. ED-001 Deliverables

  • specifications/017-editorial-design-system/editorial-design-system.md
  • specifications/017-editorial-design-system/typography.md
  • specifications/017-editorial-design-system/components.md
  • specifications/017-editorial-design-system/book-layout.md
  • specifications/017-editorial-design-system/publishing-pipeline.md

No CSS implementation is required during ED-001.

Acceptance Criteria

At the end of ED-001, the Architecture Board must be able to review the following as static mockups (not live CSS):

  • Cover page
  • Chapter opener
  • Specification page
  • ADR page
  • Reference Architecture page
  • Annex page
  • Glossary page

CSS implementation and PDF generation begin only after mockup approval.

Consequences

Positive - UC-BoK Book will have a professional, consistent editorial identity distinct from the documentation site - Design decisions are reviewable before implementation investment - The publishing pipeline is independent — documentation site remains unaffected during book development - The book will read as an architecture handbook (O'Reilly / ThoughtWorks Technology Radar style), not a wiki export

Negative / Constraints - ED-001 produces no rendered output — only design documents and mockups - Requires editorial design skills in addition to technical skills - CSS and PDF generation (ED-002) cannot begin until ED-001 acceptance criteria are met

References