Skip to content

ADR-0004: Documentation Structure and Wiki-Style Product Documentation

Status

Accepted

Date

2026-08-11

Context

Following the large rewrite (MR !4), the repository accumulated documentation from several sources and eras:

  • docs/ contains ADRs, design exploration documents, an implementation plan that predates the rewrite, and a code-review transcript.
  • specs/ contains feature specifications generated by SpecKit, which is no longer used.
  • .specify/ contains SpecKit tooling (scripts, templates, memory).

Much of this material is stale, describes features that were never implemented, or duplicates the code itself. Before deleting anything, we need a canonical structure so that useful information can be captured in the right place and future documentation is consistent.

Two kinds of documentation have proven their value and are worth formalising:

  1. Architecture Decision Records (ADRs) record why decisions were made. Existing ADRs (0001-0003) already follow a shared shape.
  2. Product documentation describing how the software works. The README is a good front door but is not the right place for in-depth reference material.

The user wants the product documentation rendered as a wiki-style site, potentially hosted on GitLab Pages.

Decision

Compulsory Documentation

Three tiers of documentation are compulsory:

  1. README.md - the front door: what the tool is, why it exists, quickstart installation and usage, and links into the product docs.
  2. ADRs (docs/architecture-decisions/) - one record per significant design decision, following the standard template.
  3. Product docs (docs/product/) - describe how the software actually works today. Initially four files:
  4. overview.md - what the tool is and its core concepts
  5. architecture.md - module map, sync flow, async model
  6. configuration.md - the canonical configuration reference
  7. data-model.md - SQLite schema, tag/UFID identity, supported formats

How-to guides for the bundled scripts (e.g. scripts/musicbrainz_migrate.py) live in docs/guides/ and are optional but encouraged.

ADR Format

ADRs follow a fixed template:

  • Title - ADR-NNNN: <Title>
  • Status - Proposed / Accepted / Superseded
  • Date
  • Context - the situation that prompted the decision
  • Decision - the decision itself
  • Consequences - positive, negative, and neutral outcomes
  • Alternatives Considered - other options and why they were rejected

ADRs are immutable once accepted. A new ADR supersedes an old one rather than editing history (e.g. ADR-0002 is superseded by ADR-0003).

Product Doc Format

  • Markdown, written for the current implementation, not an aspirational design.
  • Every claim reflects the code as it exists on main.
  • Cross-link to the relevant ADR where a design decision explains behaviour.
  • Rendered as a wiki-style site using MkDocs with the Material theme, deployed to GitLab Pages (see Consequences).

Disposal of Stale Documentation

Once the product docs above exist and any useful information from the stale files has been captured, the following are deleted:

  • specs/ (SpecKit feature specifications)
  • .specify/ (SpecKit tooling; also add .specify/ to .gitignore)
  • docs/implementation-plan.md (describes the pre-rewrite design)
  • docs/download-module-refactor.md (an AI chat transcript, not documentation)
  • docs/etag-cache-failed-downloads.md (its proposed solution was implemented; the behaviour is documented in docs/product/architecture.md)

docs/musicbrainz-bindings-spec.md and docs/musicbrainz-migration-spec.md are mined for content first; musicbrainz-migration-spec.md is replaced by a concise guide describing the real script.

Consequences

Positive

  • A clear, stable home for every kind of documentation.
  • Product docs and code cannot drift as easily because both describe current state.
  • ADRs keep capturing decision context in a standard, searchable format.
  • The wiki-style site is browseable and searchable, and deployable to GitLab Pages for free.

Negative

  • Maintaining product docs costs time on every notable change.
  • MkDocs adds a docs dependency group and a Pages CI job.
  • Product docs and README can still drift unless the README links into the docs rather than duplicating them.

Neutral

  • Existing ADRs 0001-0003 remain as historical records; ADR-0003 (hybrid filesystem state) does not match the shipped SQLite state manager and should eventually be superseded by a dedicated ADR.

Alternatives Considered

Expand the README

Rejected: the README is the wrong depth for reference material; in-depth docs would bury the quickstart and are not browseable.

Plain static Markdown (no generator)

Rejected: no site navigation or search without extra tooling; MkDocs is already Python-native and fits the uv workflow.

mdBook

Rejected: a Rust toolchain in a Python project, no material benefit over MkDocs.

Docusaurus

Rejected: heavier (React/Node) than needed for a homelab tool.

Keep SpecKit-generated specs

Rejected: SpecKit is no longer used; keeping its output would preserve process artifacts that duplicate the code and README.