Documentation
An app ships with its documentation. There are three readers and three places: the person using the app reads the
website’s docs; the person changing the app reads docs/; a coding agent reads AGENTS.md. The README is
the landing page that points to each. None of it is optional, and none of it is written after the fact: a change
that affects what a reader would learn updates the documentation in the same pull request.
Reference: Editora’s AppInfo.docsUrl(), WindowCommandRegistrar (help.documentation), MenuBarModel (the Help
menu), WelcomePane (the Help row), CommandPalette.docsUrl and SettingsFrameBits.helpUrl (deep links); the
repository’s docs/README.md, docs/conventions.md#docs-in-the-same-pr and CONTRIBUTING.md; and the
editora-website repository’s src/content/docs/ and scripts/.
Rules on this page 18
| ID | Level | Rule |
|---|---|---|
| User documentation | ||
| DOCS-01 | MUST | Every app has user documentation: a Getting started page (install, first launch, the first
thing to do), one page per feature area, the keyboard reference, the Settings, and an FAQ. It is written for the
person using the app, in their words, with screenshots from the real window. The README’s 200 lines are not it.
|
| DOCS-02 | MUST | The user docs live on the app’s website, under /docs/, in the app’s <app>-website
repository, beside the feature pages, the screenshots, the news posts and the blog. Each docs page is a Markdown
file whose frontmatter gives its category and order; the sidebar, the sitemap and the RSS feed follow. The
app’s repository never carries a second copy.
|
| DOCS-03 | SHOULD | Deep links from the app open the running version’s docs. Pages live under
/docs/v-<version>/…; bare /docs and every unversioned slug redirect to the current version, so a link in a
page never carries a version and a bump just regenerates src/lib/version.ts. The app builds the base from its
own version with -SNAPSHOT dropped, so a development build points at the release it is working toward instead
of a path that would always 404.
|
| DOCS-04 | SHOULD | Docs are generated where the app is the source. The Commands and Keybindings pages are
generated from the app’s command registrations, messages.properties and keymaps; the Roadmap and What’s new
from TODO.md and CHANGELOG.md; the version from pom.xml. The output is committed, so the site builds
without the app checked out. A check fails the site when a docs page quotes a command id that does not exist or a
chord that is bound to a different command.
|
| DOCS-05 | MUST | Release notes are written for users. Each CHANGELOG.md entry opens with a bold one-line
summary (Repository documents), and in an app with a Welcome page its What’s New opens this
build’s release. The website’s What’s new is DOCS-04; the GitHub release carrying the section is
REL-04.
|
| Reachable from the app | ||
| DOCS-06 | MUST | Help → Documentation opens the user docs in the browser. It is a command
( help.documentation), so it is in the palette, bindable and in the menu through the registry like every other
row, and an app with a Welcome page repeats it in the Help row. Its place in the Help menu is
DOCS-07.
|
| DOCS-07 | SHOULD | The Help menu runs in this order: Command Palette · Documentation · Check for Updates ·
Message Log · Debug Log · Report a Problem · Pauta Conformance · About. Simple mode keeps Command Palette, Documentation and About. An
app without a feature drops its row; nothing moves.
|
| DOCS-08 | SHOULD | Help has a keyboard reference: a searchable window of every key, grouped as the menus are,
or the keybinding editor.
|
| DOCS-09 | MUST | Every command has a one-line description ( command.<id>.desc), shown under the title in the
palette. It is the in-app documentation of the command.
|
| DOCS-10 | MAY | The palette opens per-command help. With a command highlighted, C-h opens its page,
/docs/v-<version>/commands/<id>; where the keymap binds C-h, the first free of F1 and Shift+F1 does.
Search Everywhere shares the URL builder so the two pickers can never disagree.
|
| DOCS-11 | MAY | Each page of the Settings window has a Help for <page> link to its docs page, from
one map of page to slug.
|
| Developer documentation | ||
| DOCS-12 | MUST | docs/ has an index. docs/README.md says who the folder is for (contributors; user docs
live on the website) and lists every guide with one line; that the code wins is DOCS-17. The
set is the one Repository documents names: architecture.md, conventions.md, testing.md,
gotchas.md, release.md, building-and-packaging.md and decisions/.
|
| DOCS-13 | SHOULD | Every choice a newcomer would question has a decision record: a fork, a rejected
dependency, a storage format, an escape hatch. It is one numbered Markdown file, docs/decisions/NNNN-slug.md,
with the context, the decision and what it costs.
|
| DOCS-14 | MUST | Three files have three jobs. AGENTS.md is the operational guide, kept short (what it holds
is REPO-05). CONTRIBUTING.md is the short version for a person, pointing into
docs/. docs/ holds the durable explanations. Exhaustive history goes to docs/reference/, not into any of
the three.
|
| DOCS-15 | SHOULD | Javadoc sits on its member: a doc comment above another doc comment documents nothing.
Comments say why, not what.
|
| Kept in step | ||
| DOCS-16 | MUST | Docs change in the same PR. A change that affects behavior updates CHANGELOG.md,
TODO.md, the contributor guides it touches and the website’s user docs in the same change, never as a
follow-up. A reviewer treats a feature PR with no docs change as incomplete.
|
| DOCS-17 | MUST | When documentation and code disagree, the code wins, and the documentation is fixed in the
same change. The same rule this guide applies to itself.
|
| DOCS-18 | SHOULD | Screenshots are retaken, not described. The capture hook renders the real window at 2×
after any UI change, for the README (its hero in light and dark), the website and bug reports.
|
User documentation
Section titled “User documentation”- DOCS-01 MUST Every app has user documentation: a Getting started page (install, first launch, the first
thing to do), one page per feature area, the keyboard reference, the Settings, and an FAQ. It is written for the
person using the app, in their words, with screenshots from the real window. The README’s 200 lines are not it.
- Check (code): the website repository’s
src/content/docs/has a getting-started page, a keymaps page, a settings or configuration page, an FAQ and a page per feature area. - Reference: editora-website
src/content/docs/(43 pages in nine categories, from Getting started to Help); torrenta-website (19), termina-website (16), mirada-website (11).
- Check (code): the website repository’s
- DOCS-02 MUST The user docs live on the app’s website, under
/docs/, in the app’s<app>-websiterepository, beside the feature pages, the screenshots, the news posts and the blog. Each docs page is a Markdown file whose frontmatter gives itscategoryandorder; the sidebar, the sitemap and the RSS feed follow. The app’s repository never carries a second copy. - DOCS-03 SHOULD Deep links from the app open the running version’s docs. Pages live under
/docs/v-<version>/…; bare/docsand every unversioned slug redirect to the current version, so a link in a page never carries a version and a bump just regeneratessrc/lib/version.ts. The app builds the base from its own version with-SNAPSHOTdropped, so a development build points at the release it is working toward instead of a path that would always 404.- Why: a release that pointed at another release’s docs would claim what is not true (Never claim what is not true), so this becomes a must the day the app links to a specific page.
- Check (code): the app’s docs URL is
<homepage>/docs/v-plus its version without-SNAPSHOT; the site’sastro.config.mjsserves/docs/v-<version>/and redirects the unversioned paths. - Reference: Editora
AppInfo.docsUrl(),releaseVersion(); editora-websiteastro.config.mjs,README.md(Versioned docs). The other three sites carry a comment to port these routes when their app first deep-links.
- DOCS-04 SHOULD Docs are generated where the app is the source. The Commands and Keybindings pages are
generated from the app’s command registrations,
messages.propertiesand keymaps; the Roadmap and What’s new fromTODO.mdandCHANGELOG.md; the version frompom.xml. The output is committed, so the site builds without the app checked out. A check fails the site when a docs page quotes a command id that does not exist or a chord that is bound to a different command.- Why: one fact, one source (One source of truth for each fact).
- Check (code): the website’s
scripts/holds the generators, their output undersrc/lib/is committed, andnpm run check:docsruns the id and chord check. - Reference: editora-website
scripts/GenCommands.java(everyCommand.ofin Editora’scom.editora.ui,MainControllerholding most),GenRoadmap.java,GenFeatures.java;scripts/check-doc-commands.mjs(npm run check:docs).
- DOCS-05 MUST Release notes are written for users. Each
CHANGELOG.mdentry opens with a bold one-line summary (Repository documents), and in an app with a Welcome page its What’s New opens this build’s release. The website’s What’s new is DOCS-04; the GitHub release carrying the section is REL-04.- Check (code):
CHANGELOG.md’s entries open with a bold summary; a Welcome page’s What’s New opensAppInfo.releaseNotesUrl(). - Reference: Editora
AppInfo.releaseNotesUrl(),WelcomePane(welcome.whatsNew); editora-websiteGenRoadmap.java.
- Check (code):
Reachable from the app
Section titled “Reachable from the app”The documentation is one command away, so nobody has to know the website’s address.
- DOCS-06 MUST Help → Documentation opens the user docs in the browser. It is a command
(
help.documentation), so it is in the palette, bindable and in the menu through the registry like every other row, and an app with a Welcome page repeats it in the Help row. Its place in the Help menu is DOCS-07.- Check (code):
help.documentationis registered and in the HelpMenuSpec, and a Welcome page’s Help row runs it through the registry. - Reference: Editora
WindowCommandRegistrar(help.documentation→MainController.openDocumentation()),MenuBarModel(menubar.help),WelcomePane(welcome.documentation).
- Check (code):
- DOCS-07 SHOULD The Help menu runs in this order: Command Palette · Documentation · Check for Updates ·
Message Log · Debug Log · Report a Problem · Pauta Conformance · About. Simple mode keeps Command Palette, Documentation and About. An
app without a feature drops its row; nothing moves.
- Check (code): both
menubar.helpmenu specs list those command ids in that order. - Reference: Editora
MenuBarModel, bothMenuSpec("menubar.help", …).
- Check (code): both
- DOCS-08 SHOULD Help has a keyboard reference: a searchable window of every key, grouped as the menus are,
or the keybinding editor.
- Check (by hand): open it from Help, search for a command, and find its key.
- Reference: Termina’s and Mirada’s
ShortcutsWindow; Editora’s keybinding editor (Keyboard first).
- DOCS-09 MUST Every command has a one-line description (
command.<id>.desc), shown under the title in the palette. It is the in-app documentation of the command.- Check (test): the parity test fails when a
command.<id>title has no.desc. - Reference: Editora
messages.properties,MessagesTest.everyCommandTitleHasAMatchingDescription(Code quality gates).
- Check (test): the parity test fails when a
- DOCS-10 MAY The palette opens per-command help. With a command highlighted,
C-hopens its page,/docs/v-<version>/commands/<id>; where the keymap bindsC-h, the first free ofF1andShift+F1does. Search Everywhere shares the URL builder so the two pickers can never disagree.- Check (code): the palette and Search Everywhere both build the URL with
CommandPalette.docsUrl. - Reference: Editora
CommandPalette.docsUrl,setDocsOpener;PickerKeys.freeChord.
- Check (code): the palette and Search Everywhere both build the URL with
- DOCS-11 MAY Each page of the Settings window has a Help for <page> link to its docs page, from
one map of page to slug.
- Check (code): one map from Settings page to docs slug feeds every page’s help link.
- Reference: Editora
SettingsWindow,SettingsFrameBits.helpUrl,settings.help.
Strings
Section titled “Strings”| Key | English |
|---|---|
command.help.documentation | Documentation |
command.help.documentation.desc | Open the <App> documentation site for this version in your browser. |
welcome.documentation / welcome.whatsNew | Documentation / What’s New |
settings.help | Help for {0} |
Developer documentation
Section titled “Developer documentation”- DOCS-12 MUST
docs/has an index.docs/README.mdsays who the folder is for (contributors; user docs live on the website) and lists every guide with one line; that the code wins is DOCS-17. The set is the one Repository documents names:architecture.md,conventions.md,testing.md,gotchas.md,release.md,building-and-packaging.mdanddecisions/.- Check (code):
docs/README.mdexists, says who it is for, and links each guide indocs/. - Reference: Editora’s
docs/README.md; the template’sdocs/.
- Check (code):
- DOCS-13 SHOULD Every choice a newcomer would question has a decision record: a fork, a rejected
dependency, a storage format, an escape hatch. It is one numbered Markdown file,
docs/decisions/NNNN-slug.md, with the context, the decision and what it costs.- Check (code):
docs/decisions/holdsNNNN-slug.mdfiles, each with context, decision and consequences. - Reference: Editora’s
docs/decisions/(18 records, from0001-richtextfx-fork.md).
- Check (code):
- DOCS-14 MUST Three files have three jobs.
AGENTS.mdis the operational guide, kept short (what it holds is REPO-05).CONTRIBUTING.mdis the short version for a person, pointing intodocs/.docs/holds the durable explanations. Exhaustive history goes todocs/reference/, not into any of the three.- Check (code):
AGENTS.mdandCONTRIBUTING.mdlink intodocs/; long catalogs sit underdocs/reference/. - Reference: Editora’s
AGENTS.md(Documentation map),CONTRIBUTING.md,docs/reference/README.md.
- Check (code):
- DOCS-15 SHOULD Javadoc sits on its member: a doc comment above another doc comment documents nothing.
Comments say why, not what.
- Check (test): a test fails the build on a Javadoc comment followed by another.
- Reference: Editora
StackedJavadocTest.
Kept in step
Section titled “Kept in step”- DOCS-16 MUST Docs change in the same PR. A change that affects behavior updates
CHANGELOG.md,TODO.md, the contributor guides it touches and the website’s user docs in the same change, never as a follow-up. A reviewer treats a feature PR with no docs change as incomplete.- Check (code):
docs/conventions.md,CONTRIBUTING.mdandAGENTS.mdstate the rule; in review, a feature PR’s diff touchesCHANGELOG.md. - Reference: Editora
docs/conventions.md#docs-in-the-same-pr,CONTRIBUTING.md(step 4),AGENTS.md.
- Check (code):
- DOCS-17 MUST When documentation and code disagree, the code wins, and the documentation is fixed in the
same change. The same rule this guide applies to itself.
- Check (code):
AGENTS.mdanddocs/README.mdsay so. - Reference: Editora’s
AGENTS.md,docs/README.md.
- Check (code):
- DOCS-18 SHOULD Screenshots are retaken, not described. The capture hook renders the real window at 2×
after any UI change, for the README (its hero in light and dark), the website and bug reports.
- Why: a stale screenshot claims what is not true.
- Check (by hand): the README’s hero and the website’s screenshots show the current UI; they are rendered with the capture hook QUAL-09 asks for, not drawn or described.
- Reference:
DevCapture(Shared features); Editora’s headless harness.
The README’s own shape, about 200 lines that leave the detail to the website’s docs, is REPO-01.
Pauta 5.0.0 · · Changelog · This page in the latest edition