aureliasrs specifications
Convention specification

Owner Documentation

Conventions are described beside the thing that owns them — a directory’s layout in its own README, a command’s behaviour in its module or script.

Applies at
<area>/README.md
Status
Stable

01 Defines

The practice of documenting each area of a repository in a README.md inside that area, opened by a common header that names the area, describes it in one line, and links to its fuller specification.

02 Applies when

  • A directory has a purpose, a layout, or rules a contributor needs before adding to it.
  • A command, module, or script has behaviour worth explaining to its callers.
  • A convention would otherwise be recorded far from the files it governs.

03 Boundaries

  • Repository-wide navigation belongs in the code map, which links to owner documentation rather than repeating it.
  • Decisions that no single owner can explain go to a decision record instead.
  • Owner documentation describes the area; operating guides and product context live in docs/.

Expected behaviour

  1. 01
    Each top-level area carries a README.md explaining what belongs there and the rules for adding to it.
  2. 02
    Commands explain their behaviour in Makefile modules, scripts, and workflow files.
  3. 03
    Infrastructure roots and modules document their runtime contract locally.
  4. 04
    Area READMEs open with a header table — icon, title, and one-line description — before the body.
  5. 05
    Most area READMEs close with a short Rules list that states the area’s conventions in a few lines.

Behaviour#

A reader who opens a directory is already looking at the thing they want to understand. Owner documentation meets them there. The README beside the files says what the area is for, what belongs in it and what does not, and the handful of rules that keep it coherent. Moving or deleting the area takes its documentation with it.

The same principle applies below the directory level. A make module explains itself in its header comment, a script in its usage line, a workflow in its file header. The decision-record guidance lists these owners explicitly and asks for a separate record only when none of them can carry the explanation.

Where documentation lives#

The header pattern#

Every area README opens the same way: an HTML table with the area’s icon on the left and, on the right, a bold title and a one-line description. The icon lives beside the README in a local .assets/img/ directory and links out — to the upstream documentation for a tool, or to the area’s page in this library. A horizontal rule separates the header from the body, which typically runs through purpose, design, and a closing Rules list.

.descriptor/README.md 
<table style="width: 100%; border-style: none;">
  <tr>
    <td style="width: 80px; text-align: center;">
      <a href="https://specifications.aureliasrs.ca/catalog-descriptors">
        <img width="64px" src="./.assets/img/icon.svg" alt="actions logo" />
      </a>
    </td>
    <td>
      <strong>Catalog Descriptors</strong><br />
      Repository-owned catalog metadata describing the repository, ownership
      information, published artifacts, and related operational references<br />
    </td>
  </tr>
</table>

Examples#

The decision-record guidance is itself the clearest statement of the pattern:

docs/pdlc/decisions/README.md 
Prefer expressing repository conventions beside the thing that owns them:

- directories explain their layout in local `README.md` files;
- commands explain behavior in `Makefile` modules, scripts, and workflow files;
- infrastructure roots and modules document their runtime contract locally;
- tests enforce architectural conventions that must survive routine change.

The code map closes the loop from the other side: “Open the local README.md of an area for detail.”

Connections

How Owner Documentation relates to the library

Owner Documentation and 4 related specificationsReference Over DuplicationReference Over DuplicationCode MapCode MapDecision RecordsDecision RecordsToolsTools
RefinesComposesRelies onFollowed byContrasts with

Relies on

Relied on by