ADR-0091: The user manual lives in the source tree

Status: Accepted
Date: 2026-09-10
Deciders: jka
Decision: D91

Context

rio had documents for contributors, deployment and rough edges, but nothing that told a user how to use the editor. The usage material that existed had drifted into INSTALL.md, and its shortcut table was missing seven commands. The earlier plan was a separate wiki repository.

Decision

The user manual is Markdown in docs/ in the source tree, written so rio can later display it as built-in help, in the manner of WinHelp: a contents page, topic pages, links between them, F1.

One topic per file. The file name is the topic id; it is stable and not renamed casually, because links and future context help depend on it.
index.md is the contents. Each page's first heading is its title and matches its contents entry.
Links between topics are relative.
A restricted Markdown subset: headings, paragraphs, lists, inline code, fenced blocks, links, bold and italic, simple pipe tables, block quotes. No HTML, images, footnotes, nested tables or task lists. Each construct maps onto a Tk text tag or an indent.
Second person, present tense, the rule and a one-line reason, no decision numbers.
Each fact has one home: the manual covers use, INSTALL.md installation and deployment, CAVEATS.md rough edges. Pages link rather than repeat.
A stub page is allowed if it states its scope and points to where the facts are today.

Alternatives considered

A separate wiki repository. In-tree documentation ships with rio (a help viewer needs local files), versions with the code so a feature and its page land in one commit, and is reviewed in the same diff.

Consequences

Help can be built on top of files that already exist (ADR-0099, ADR-0100).
Facts copied from code into the manual (the shortcut table, preference keys, file locations) need guards against drift (ADR-0117).
Maintenance of the manual's prose is delegated to a separate documentation workflow described in DOCS.md.