Skip to content

ADR-0018: MkDocs Material and Technical Writer Agent

  • Status: Accepted
  • Date: 2026-03-26
  • Deciders: DeAcero Agentic Team
  • Supersedes: None

Context

As Cornerstone becomes the baseline scaffolding for multiple 2026 analytical projects, its documentation footprint will scale remarkably. Currently, documentation lives as disjointed Markdown files scattered across docs/ and root directories without a consolidated, navigable web footprint comparable to modern python libraries like Kedro or FastAPI. Additionally, maintaining updated technical documentation represents a substantial overhead that usually degrades over time in fast-moving agentic workflows.

Decision

  1. Adopt MkDocs + Material Theme: We will adopt mkdocs and mkdocs-material as the standard, first-class documentation SSG (Static Site Generator) for the entire DeAcero group, enforcing its installation inside [dev] dependencies for all projects generated via Cornerstone.
  2. Autonomous Documentation Maintenance: We introduce the technical-writer autonomous agent under .agents/skills/software/quality/. This agent is exclusively tasked with writing, linking, and maintaining MkDocs definitions, docs/**/*.md sites, and in-code python docstrings to guarantee living documentation.

Consequences

Positive

  • World-class developer experience with instantly searchable, beautifully formatted static sites via mkdocs serve.
  • Living documentation becomes a dedicated agentic responsibility rather than an afterthought.
  • Consistent documentation taxonomy out-of-the-box for all 65 migrations.

Negative

  • Adds minor local setup dependency weight (mkdocs-material is heavy).
  • Developers must rely on mkdocs build instead of solely reading raw Git Markdown for the complete UX.