// SPDX-License-Identifier: CC-BY-SA-4.0
= README + EXPLAINME Authoring Standard
:toc: preamble
:toc-title: Contents
:icons: font
:doctype: article
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
v1.0, 2026-04-12

[NOTE]
====
This standard governs both `README.adoc` and `EXPLAINME.adoc` across the
entire Hyperpolymath estate. Every RSR-compliant repo MUST have both files.
Exceptions are listed in <<exceptions>>.
====

== Purpose and relationship between the two files

[cols="1,2,2", options="header"]
|===
| File | Audience | Job

| `README.adoc`
| Curious outsider — first 90 seconds
| Pitch, overview, quick-start. Makes the reader want to use or contribute.

| `EXPLAINME.adoc`
| Sceptical developer — post-interest due-diligence
| Proves every README claim with code paths and honest caveats. Shows the
  technology is real and dogfooded. Backs up the story with receipts.
|===

These are complementary, not redundant. README sells; EXPLAINME proves.
An EXPLAINME that only repeats README prose fails its purpose.

== README.adoc specification

=== Required format

* AsciiDoc (`.adoc`) — **not** Markdown. GitHub-required files (`SECURITY.md`,
  `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`) remain `.md` as a platform exception.
* Header: `// SPDX-License-Identifier: MPL-2.0` (or applicable licence).
* Document title (`= Title`) in sentence case, not ALL CAPS.
* `:toc: preamble` and `:icons: font` attributes.
* Ends with a `== License` section referencing `LICENSE`.

=== Required sections

[cols="1,2,1", options="header"]
|===
| Section heading | Contents | Required?

| Badges (below title)
| OpenSSF Best Practices, OpenSSF Scorecard. Both SHA-pinned.
| Yes for public repos

| Overview / About
| One or two sentences: what is this, who is it for, what problem does it solve.
  No jargon. Assume the reader has never heard of the project.
| Yes

| Features / What it does
| Bullet list of concrete capabilities. Not aspirations — only what is implemented.
  If something is planned, put it in a `[NOTE]` block labelled `Planned`.
| Yes

| Quick Start
| Minimal working example. Source block with language tag. Must be accurate.
  Link to `EXPLAINME.adoc` at the end: "Wondering how this works?
  See link:EXPLAINME.adoc[]".
| Yes

| Repository Layout
| `[cols="1,3"]` table mapping top-level paths to purposes.
  Omit generated and cached directories.
| Yes for repos with non-obvious structure

| Documentation
| Bulleted list of named links to EXPLAINME.adoc, CONTRIBUTING.md, SECURITY.md,
  and any project-specific docs.
| Yes

| License
| `SPDX-License-Identifier: MPL-2.0` + link to `LICENSE`.
| Yes
|===

=== What NOT to put in README

* Marketing superlatives ("industry-leading", "revolutionary") without proof.
* Architecture deep-dives — those belong in EXPLAINME or `docs/`.
* Anything that will go stale quickly (exact version numbers, benchmark figures)
  unless you commit to keeping them current.
* Duplicate information already in EXPLAINME.
* Inline images from external CDNs (badge images excepted).

=== Accuracy invariant

Every claim made in README must be backed by a corresponding entry in EXPLAINME.
If you cannot write the EXPLAINME entry, the claim must not appear in README.

== EXPLAINME.adoc specification

=== Purpose

EXPLAINME is the "Show Me The Receipts" file. It exists because:

. Sceptical developers see ambitious READMEs and assume vapourware.
. EXPLAINME proves the logic is real without being a textbook.
. It makes the codebase navigable: a new contributor can find any claim in code.
. It enforces README accuracy by requiring implementation evidence for each claim.

=== Required format

* AsciiDoc (`.adoc`).
* Header: `// SPDX-License-Identifier: MPL-2.0`.
* Document title: `= {ProjectName} — EXPLAINME`.
* `:toc: preamble` and `:icons: font`.
* Opening sentence: one line explaining what this file is for and who should read it.

=== Required sections

==== 1. Claim-to-implementation map

One section per major README claim. Each section:

[source,asciidoc]
----
=== {Claim heading (quote the README claim verbatim)}

[quote, README.adoc]
____
{paste the exact README text being backed up}
____

How this is implemented::
Brief prose + named code paths. Use `link:path/to/file.ext[]` links.

Caveat::
Honest limitation. If none, write "None currently known."
----

Do not summarise every line of code. One to three sentences plus a file path
is enough. Link to external documentation for well-known technologies
(e.g. `link:https://ziglang.org/documentation/[Zig docs]`) rather than
re-explaining them.

==== 2. Dogfooding table

Demonstrates the technology is used across the estate, not just in this repo.

[source,asciidoc]
----
== Dogfooded Across The Account

[cols="1,2,2", options="header"]
|===
| Technology / Pattern | Used here | Also used in

| {Technology}
| {What this repo does with it}
| link:https://github.com/hyperpolymath/{repo}[{repo}]
|===
----

At minimum list the three most distinctive technologies or patterns.

==== 3. Known gaps

Honest list of what is promised by README but not yet complete. Use CAUTION
admonition blocks.

[source,asciidoc]
----
[CAUTION]
====
{feature}: README claims X but current implementation only covers Y.
Tracked in link:https://github.com/hyperpolymath/{repo}/issues/{n}[#{n}].
====
----

If there are no known gaps, write: "No known gaps between README claims and
current implementation."

==== 4. Evidence index (optional but strongly encouraged)

For repos with significant test suites or proofs:

[source,asciidoc]
----
== Evidence Index

[cols="2,3", options="header"]
|===
| Path | Proves

| `src/foo.ext`
| {What this file demonstrates}
|===
----

=== What NOT to put in EXPLAINME

* Repeated README prose without the claim→implementation structure.
* Aspirational future work (that goes in README under `[NOTE]` or in ROADMAP).
* Tutorial-style walkthroughs — EXPLAINME is evidence, not a guide.
* Empty sections ("This section is coming soon").

=== Completeness criteria

An EXPLAINME is considered **complete** when:

. Every section heading in README that makes a factual claim has a corresponding
  EXPLAINME entry.
. Every EXPLAINME entry has: a quoted claim, an implementation note with at least
  one code path, and a caveat (even if "None currently known.").
. The dogfooding table has at least three rows.
. No section is a stub (placeholder text, TODO, or "coming soon").
. The file compiles without AsciiDoc warnings.

== File naming and placement

[cols="1,2", options="header"]
|===
| File | Location

| `README.adoc`
| Repository root only. One per repo.

| `EXPLAINME.adoc`
| Repository root only. One per repo.

| `README.md`
| **Banned** in all hyperpolymath-owned repos. GitHub renders `.adoc` natively.
  Only permitted in upstream fork checkouts (see <<exceptions>>).

| Localised variants (`README-ja.md`, etc.)
| Only in upstream fork checkouts. Do not add to hyperpolymath-authored content.
|===

[NOTE]
====
GitHub-required files (`SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`,
`CHANGELOG.md`) remain `.md` as a platform exception — GitHub Actions and the
security advisory system expect `.md` for these.
====

[[exceptions]]
== Exceptions

[cols="1,2", options="header"]
|===
| Repo / Pattern | Exception rationale

| Upstream fork checkouts (`awesome-gleam`, `awesome-zig`, `file`, `HOL`,
  `rescript`, `linguist`, …)
| These repos track upstream projects not owned by Hyperpolymath. Modifying
  their README would create merge conflicts on every upstream pull. Leave
  as-is. Do not add EXPLAINME.adoc to forks.

| `repos-monorepo` subdirectories
| Subdirectories inside `repos-monorepo` are project directories, not
  standalone repos. They do not need individual `README.adoc` files;
  their parent monorepo's README covers them.

| Monorepo top-level subdirs (`developer-ecosystem/`, `nextgen-languages/`,
  `nextgen-databases/`, etc.)
| Top-level subdir READMEs are `adoc` with reduced scope (subproject overview
  + link to parent monorepo README).
|===

== AsciiDoc style rules

* Headings: sentence case, not Title Case.
* Code blocks: always include language tag (e.g. `[source,bash]`, `[source,rust]`).
* Tables: always include `options="header"` for tables with a header row.
* Lists: use unordered (`*`) for unordered content, ordered (`.`) for steps.
* Notes/Cautions/Warnings: use AsciiDoc admonition blocks, not emoji.
* Internal links: `link:path/file.ext[]` for relative, `link:URL[]` for external.
* Footnote references: use `footnote:[text]` not manual numbering.
* Line length: wrap at 80 columns in source; rendered output is unconstrained.

== Enforcement

* `rsr-template-repo` provides canonical `README.adoc` and `EXPLAINME.adoc`
  templates. Run `just init` after cloning to populate placeholders.
* `panic-attack assail` checks for README/EXPLAINME presence (file-exists rule).
* Hypatia rule module `docs_standards` (planned) will lint completeness criteria.
* CRG grade C gate requires both files to be non-stub.

== See also

* link:../a2ml/[A2ML specification] — machine-readable metadata complement
  to human-readable docs.
* link:https://github.com/hyperpolymath/rsr-template-repo[rsr-template-repo]
  — canonical templates for both files.
* link:../UX-standards/[UX standards] — overlapping requirements for
  user-facing documentation.
* link:../immaculate-guide/[Immaculate Guide] — prose style and tone guide.
