Skip to main content

ADR-010: Documentation Framework — Arc42 + ADRs + Specs Before Code

Status: Accepted Date: 2026-03-16

Context​

PSSaaS is a complex system being ported from a 30-year-old codebase. The team is small (CTO + AI agents initially), and future developers must be able to onboard from documentation alone. The project needs a structured documentation approach that scales with the team and prevents knowledge loss.

Options considered:

  • Ad hoc documentation: Write docs as needed, no structure. Risk: inconsistency, gaps, hard to navigate.
  • Arc42 + ADRs: Industry-standard architecture documentation template with formal decision records.
  • C4 Model: Focuses on diagrams (Context, Container, Component, Code). Good for visualization, weak on decisions and quality requirements.
  • Custom framework: Build a documentation structure from scratch. Risk: reinventing the wheel.

Decision​

Follow the Arc42 template for architecture documentation. Capture all architectural decisions as ADRs. Write feature specifications before writing code. Maintain a devlog for narrative record of development progress.

Key disciplines:

  • Arc42: 11 sections covering introduction through risks. Living document updated as architecture evolves.
  • ADRs: Numbered, immutable records. Context → Decision → Consequences. Never renumbered. Superseded ADRs link to their replacements.
  • Specs before code: Every feature has a written specification (requirements, business rules, API design, data model, acceptance criteria) before implementation begins.
  • Devlog: Narrative entries recording what was done, why, and what was learned. Supplements formal docs with human context.

Consequences​

Positive:

  • Consistent with other products: MBS Access has 37+ ADRs, PowerSeller X has 39 ADRs. Same discipline across the ecosystem.
  • Onboarding from docs: Future developers (Rudy, new hires) can understand the system from documentation before reading code
  • Reduced rework: Specs catch design issues before code is written
  • Knowledge preservation: Greg's domain knowledge is captured in specs, not just code

Negative:

  • Higher upfront cost: Writing specs takes time before any code is written
  • Documentation maintenance: Docs must be kept current as the system evolves (mitigated by treating docs as code — PRs, reviews, CI)
  • Risk of over-documenting: Discipline needed to document what matters, not everything