87 lines
3.7 KiB
Markdown
87 lines
3.7 KiB
Markdown
# Documentation style guide
|
|
|
|
This guide applies to all documentation in this repo — ADRs, architecture notes, site
|
|
files, templates, and the README. It exists so contributors (human and AI) produce
|
|
consistent, reusable documentation without needing to re-derive these conventions each time.
|
|
|
|
---
|
|
|
|
## Write for any community, not just OSArch
|
|
|
|
**OSArch is the reference implementation, not the intended audience.**
|
|
|
|
This system is designed to be forked and adopted by any open source community. Every
|
|
document in this repo should be readable and useful to a contributor from a community
|
|
that has never heard of OSArch. Write as if the reader is setting this up for their
|
|
own community from scratch.
|
|
|
|
**What this means in practice:**
|
|
|
|
- Use generic examples by default: `alice`, `bob`, `contributor-a`, `add-new-platform`,
|
|
`any-community`. Reserve named examples for situations where the OSArch context adds
|
|
genuine clarity.
|
|
- When an OSArch-specific example is genuinely the clearest choice, frame it explicitly:
|
|
*"for example, in the OSArch reference implementation..."*
|
|
- Do not assume the reader knows what OSArch is, who its contributors are, or which
|
|
platforms it uses.
|
|
- Platform references (`community.osarch.org`, `wiki.osarch.org`, `#OSArch:matrix.org`)
|
|
belong in `docs/sites/active/` — not in ADRs, architecture docs, or templates.
|
|
|
|
**What this does not mean:**
|
|
|
|
- Do not scrub OSArch from the repo. It is the living example of the system in use and
|
|
that context has value.
|
|
- OSArch-specific rationale (why a particular site was included, why a weight was set)
|
|
belongs in site files and is appropriate there.
|
|
- The README's introductory framing ("OSArch is the reference community") is correct and
|
|
should be preserved.
|
|
|
|
**The test:** Read the document as if you have no knowledge of OSArch. Does it still make
|
|
sense? Could you act on it for your own community? If yes, it passes. If not, generalise.
|
|
|
|
---
|
|
|
|
## Changelog entries
|
|
|
|
Every substantive commit must have a corresponding `CHANGELOG.md` entry. The pre-commit
|
|
hook enforces this — see [Contributing](../README.md#contributing) for setup.
|
|
|
|
Each entry should answer:
|
|
- What changed (specific files and what happened to them)
|
|
- Why (the motivation — a constraint, a community decision, a problem being solved)
|
|
- What it means going forward (consequence for future contributors or forks)
|
|
|
|
Do not summarise the diff. The diff is already in git. Explain the reasoning the diff
|
|
does not show.
|
|
|
|
---
|
|
|
|
## ADR conventions
|
|
|
|
- State the decision clearly and early — one bold sentence at the top of the Decision section
|
|
- Record alternatives considered and why they were rejected — the reasoning matters more
|
|
than the outcome
|
|
- Status is one of: `Proposed`, `Accepted`, `Superseded by ADR NNN`
|
|
- Cross-link to related ADRs using section anchors where relevant
|
|
- Write for the community-agnostic audience (see above) — use generic examples, frame
|
|
OSArch references explicitly
|
|
|
|
---
|
|
|
|
## Site files (`docs/sites/active/`, `docs/sites/proposed/`)
|
|
|
|
Site files are explicitly OSArch-specific — they record which platforms the OSArch
|
|
community has decided to collect from and why. OSArch-specific language is appropriate
|
|
and expected here. Platform mechanics (API details, signals, rate limits) belong in
|
|
`docs/sites/platforms/` and should be written generically so any community can reuse them.
|
|
|
|
---
|
|
|
|
## General tone
|
|
|
|
- Write for a reader who is encountering this document cold, with no context from prior
|
|
conversations or sessions
|
|
- Prefer plain statements over hedged ones — "the system does X" not "the system might
|
|
potentially do something like X"
|
|
- No multi-paragraph preambles — state the point, then support it
|
|
- Default to no comments in code; when a comment is needed, explain the *why*, not the *what*
|