Skip to content

ADR 0001: Human First Documentation Structure

Status

Accepted

Context

dirac-abs is a MkDocs site intended first for human readers, especially developers working on ABS service models, asset behavior, bundles, entitlements, and IoT-facing workflows.

Agent-readable files such as docs/agent/ and docs/context/ are useful, but they are support material rather than the primary reading experience. A previous normalization pass provisioned those files without also establishing a clear human-first documentation structure.

Decision

  • The MkDocs navigation for dirac-abs should be human-first.
  • Architecture, models, development guidance, ADRs, and reference material should come before agent-facing context.
  • Agent-facing pages should remain in the repo, but appear last in the public navigation.
  • The repo should expose explicit docs/adr/ and docs/reference/ sections as part of the normalized baseline.

Consequences

  • Human readers get a clearer top-level navigation order.
  • Agent support remains available without dominating the site structure.
  • Future normalization or cleanup work should preserve this ordering unless the repo owner explicitly changes it.