Skip to content

Commit 9408caf

Browse files
tazlintazlin
committed
docs: documentation and pull request standards
Introduces two meta-documentation files establishing standards for the Haidra-Org repositories: - `docs/meta/documentation.md`: Governs in-repo docs structure using Diátaxis classes, opening summaries, progressive disclosure, reference code maps, and ADR conventions. - `docs/meta/pull_requests.md`: Governs PR descriptions, requiring an upshot-first opening and explicit behavior boundary, with recommended elements for reviewers.
1 parent f200a33 commit 9408caf

2 files changed

Lines changed: 199 additions & 0 deletions

File tree

‎docs/meta/documentation.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Haidra Documentation Standard
2+
3+
This document governs in-repository documentation (the `docs/` tree) for Haidra-Org repositories. It applies to
4+
documents written for contributors and operators, not to docstrings, which are covered by [python.md](python.md).
5+
6+
In brief:
7+
8+
- Organize `docs/` by [Diátaxis](https://diataxis.fr/) class, with `docs/README.md` as the index.
9+
- Open every document with a summary that survives truncation.
10+
- Order headings from overview to detail so a reader can stop at any depth.
11+
- Give reference documents a code map from concept to file and symbol.
12+
- Record decisions as one-per-file ADRs under `docs/decisions/`.
13+
14+
These rules are prescriptive. Deviate where the document is better for it, and state the reason in review.
15+
16+
## On these rules
17+
18+
These rules are opinionated and exist for consistency across repositories. They do not claim to be the only workable
19+
set. Change proposals are welcome where a rule is overly restrictive, missing, or could be improved.
20+
21+
## Organization
22+
23+
Documents are filed by Diátaxis class: `explanation/`, `reference/`, `how-to/`, and `tutorial/`, using only the classes
24+
a repository actually needs. `docs/README.md` indexes the tree and says what each document holds.
25+
26+
Diátaxis settles where a document is filed and what mode it is written in. The rules below govern quality, and they
27+
apply within every class.
28+
29+
## Opening summary
30+
31+
Every document opens with a summary a reader can stop after and still know what the document covers, who it is for, and
32+
where to go next.
33+
34+
- It is positional. It comes first, before any other heading or body content.
35+
- It is at most roughly ten lines or five bullets.
36+
- It is introduced plainly with `TL;DR`, `Too long; didn't read`, and `If you read nothing else`, `In brief:` or
37+
carries no label at all.
38+
39+
## Progressive disclosure
40+
41+
Heading hierarchy runs from overview to detail. A reader who stops at `##` has a correct picture at lower precision
42+
than a reader who continues to `###`. Detail refines the level above it and never contradicts it.
43+
44+
## Reference documents
45+
46+
A reference document includes a code map: a table from concept or responsibility to the file and symbol that implements
47+
it.
48+
49+
| Concept | File | Symbol |
50+
| ------- | ----------------------- | ------------- |
51+
| Job pop | `horde/apis/v2/base.py` | `JobPop.post` |
52+
53+
The code map exists so the document launches a reader into the code. A reference document describes contracts and
54+
intent; the code remains the authority on behavior.
55+
56+
Where a document states a testable contract, it also names the test that covers it, so a reader can confirm the
57+
contract holds and a maintainer can see what breaks when it changes.
58+
59+
## Headings and prose
60+
61+
- Headings name the content beneath them. A heading never describes the document, its length, or the reader's
62+
attention.
63+
- Summaries are positional. Their placement identifies them, so they need no performative label.
64+
- Confidence comes from specifics: numbers, file names, measured values. Adjectives do not supply it.
65+
- No em dashes. Use a colon, a full stop, a parenthetical, or a comma.
66+
- Avoid the "not X, but Y" construction. State what is true.
67+
- Write in the present tense and describe behavior as it is. Milestone, incident, and point-in-time language ages out
68+
of date and is disallowed.
69+
70+
## Cross-linking
71+
72+
Explanation, reference, and how-to documents link to each other at the point where the other document becomes relevant,
73+
and each link says what the target holds. A reader following a link knows before clicking whether it answers their
74+
question.
75+
76+
## Site navigation
77+
78+
Where a repository publishes its `docs/` tree as a site, navigation obeys four rules:
79+
80+
- Top-level navigation mirrors the Diátaxis classes, ordered Home, Explanation, Reference, How-to, then supporting
81+
sections. A reader's first choice on the site is the same choice the directory structure makes.
82+
- Navigation lists curated documents. A generated corpus (decision records, generated API references) enters navigation
83+
as its single index page; its members are reached through that index, cross-links, and search. Navigation size must
84+
not grow with corpus size.
85+
- Navigation depth stays within two levels. Structure deeper than that belongs inside a page, where the table of
86+
contents carries it.
87+
- The landing page routes by intent within its opening summary: which class answers which kind of question, each named
88+
with a link. A reader should spend their first screenful choosing a direction, never decoding the site.
89+
90+
## Maintenance
91+
92+
A documentation change lands in the same pull request as the behavior change it describes. Documentation that trails
93+
the code it documents is treated as a defect in that pull request.
94+
95+
A repository publishing its docs runs the gates in CI: the site builds in strict mode, every generated index verifies
96+
clean against its records (`--check`), license compliance passes, and internal links resolve. A generated file that can
97+
drift from its inputs without failing CI will.
98+
99+
## Architecture Decision Records
100+
101+
Decisions live in ADRs, one decision per file, at `docs/decisions/NNNN-kebab-title.md` with a zero-padded four-digit
102+
sequence number.
103+
104+
Records use [MADR 4](https://adr.github.io/madr/): YAML front matter carrying at least `status` and `date`
105+
(`decision-makers`, `consulted`, and `informed` where they add information), then Context and Problem Statement,
106+
Decision Drivers, Considered Options, and Decision Outcome with its Consequences. Alternatives that were weighed appear
107+
in Considered Options, each with the reason it was rejected under Pros and Cons of the Options. The remaining optional
108+
MADR sections (Confirmation, More Information) are used only when they earn their length.
109+
110+
In REUSE-compliant repositories, SPDX tags go in an HTML comment between the front matter and the title. A `#`-prefixed
111+
tag inside the front matter can be mistaken for a Markdown heading, and therefore the record's title, by publishing
112+
tools.
113+
114+
`status` is one of MADR's values:
115+
116+
- `proposed`
117+
- `rejected`
118+
- `accepted`
119+
- `deprecated`
120+
- `superseded by ADR-NNNN`
121+
122+
A superseding record links to the record it replaces under More Information, and the superseded record's status names
123+
and links its replacement. A decision changed in part stays `accepted` and links its amendment under More Information,
124+
two ways as well.
125+
126+
The directory stays flat and numbers are global: never reused, never renumbered, never sharded into subdirectories.
127+
Topical organization belongs to the index. While a repository holds few records, `docs/README.md` lists them; past
128+
that, `docs/decisions/README.md` indexes them, grouped by system and showing status.
129+
130+
An accepted record is immutable in substance. Permissible edits are typo fixes and repairing file or symbol references
131+
that the codebase has moved out from under the record. Context, Decision Outcome, and Consequences are never rewritten
132+
to match later reality; a changed decision gets a new record.
133+
134+
The records are the asset; publishing tooling is replaceable and is not part of this standard. A browse surface, when a
135+
repository or the organization wants one, is a static site built from the same flat directory the records live in, with
136+
its index generated from the records' front matter rather than maintained by hand. Any tool that renders a Markdown
137+
tree qualifies, and the corpus must remain readable and complete without one. Two branches can claim the same `NNNN`
138+
number; a number is final when its record merges, and a collision is resolved by renaming before merge.
139+
140+
Reference documents and pull requests link to the relevant ADR rather than restating its reasoning.

‎docs/meta/pull_requests.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Haidra Pull Request Standard
2+
3+
This document governs pull request descriptions for Haidra-Org repositories.
4+
5+
In brief:
6+
7+
- Two things are required: the upshot first, and an explicit behavior boundary.
8+
- Everything else follows the change, its audience, and the repository.
9+
- The recommended elements below are used when the change warrants them and omitted when it does not.
10+
11+
A description exists to get a reviewer to a correct decision quickly. A one-line dependency bump and a scheduler
12+
rewrite need different descriptions, so this document fixes only what every description needs.
13+
14+
## Requirements
15+
16+
### Upshot first
17+
18+
The opening paragraph states what the change does, why it is being made, and what happens when it is deployed. The
19+
first line stands alone as a complete summary of the change, following
20+
[Google's CL description guidance](https://google.github.io/eng-practices/review/developer/cl-descriptions.html).
21+
22+
A reader who sees only the title and first line in a notification or a commit log knows what landed.
23+
24+
### Behavior boundary
25+
26+
A pull request that changes behavior states what changes and what deliberately does not.
27+
28+
Distinguish a changed outcome from a changed mechanism that produces an identical outcome. A reviewer needs to know
29+
which parts of a diff they must reason about for correctness and which parts they can confirm are equivalent.
30+
31+
## Recommended elements
32+
33+
- **Review order.** Suggest a path through the diff that separates the core of the change from mechanical fallout, so a
34+
reviewer spends attention where the argument is.
35+
- **Verification with specifics.** Give test counts, measurements against production data, and reproduction commands.
36+
State plainly what was not verified.
37+
- **Permalink excerpts.** Quote the hunks that carry the argument, linked by commit permalink so they stay valid as the
38+
branch moves.
39+
- **Links to durable rationale.** Reasoning that outlives the review belongs in an ADR or a reference document (see
40+
[documentation.md](./documentation.md)). Link to it from the pull request rather than restating it.
41+
- **Deployment ordering.** Where rollout is order-sensitive, say what must happen before and after the merge, including
42+
migrations and configuration changes.
43+
- **Incidental changes.** Call out formatting catch-up and drive-by fixes so reviewers can discount them.
44+
45+
## Exemplars
46+
47+
These pull requests calibrate depth and tone:
48+
49+
- [AI-Horde#533](https://github.com/Haidra-Org/AI-Horde/pull/533)
50+
- [AI-Horde#534](https://github.com/Haidra-Org/AI-Horde/pull/534)
51+
52+
## Prose
53+
54+
Pull request text follows the heading and prose rules in [documentation.md](./documentation.md).
55+
56+
## On these rules
57+
58+
These rules are opinionated and deliberately narrow. Change proposals are welcome where a requirement is overly
59+
restrictive, missing, or could be improved.

0 commit comments

Comments
 (0)