ADR-001 — Docusaurus 3 over MkDocs Material
Why this portfolio is built on Docusaurus 3 rather than MkDocs Material, the other strong contender for static documentation sites.
6 docs tagged with "decisions"
View all tagsADR-002 — Google Developer Style Guide over Microsoft Writing Style Guide
Why the portfolio's Vale configuration lints against the Google Developer Documentation Style Guide rather than the Microsoft Writing Style Guide.
ADR-003 — Diátaxis as page-level taxonomy, one type per page
Why every page in the portfolio is exactly one of the four Diátaxis types, and why the rule is enforced at the page level rather than at the section level.
ADR-004 — Vale CI blocks on error, not warning-only
Why the Vale job in the docs-quality CI pipeline fails the pull request on prose-lint errors instead of surfacing them as warnings.
ADR-005 — OpenAPI specs are the single source of truth for API reference
Why every API reference page on this site is generated from an OpenAPI spec, and why none of the generated pages are edited by hand.
Architecture decision records
Index of the architecture decision records (ADRs) that document the non-obvious technology and content choices behind this portfolio.