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/.
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); the GitHub release carries the section, the Welcome page’s What’s New opens this build’s release, and the website’s What’s new is generated from the same file.- Check (code): the Welcome page’s What’s New opens
AppInfo.releaseNotesUrl(); the website’s What’s new is generated fromCHANGELOG.md. - Reference: Editora
AppInfo.releaseNotesUrl(),WelcomePane(welcome.whatsNew); editora-websiteGenRoadmap.java.
- Check (code): the Welcome page’s What’s New opens
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; it is the first row of the Help menu after the Command Palette, and the Welcome page’s Help row repeats it.- Check (code):
help.documentationis registered, followspalette.showin the HelpMenuSpec, and the 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), states that the code wins when the two disagree, and lists every guide with one line. 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 those two things, 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 (commands, worktree-per-task, the change checklist).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 (code): the app has a capture hook or a headless harness that writes the real window to a PNG.
- Reference:
DevCapture(Shared features); Editora’s headless harness.
- DOCS-19 MUST The README defers. It is about 200 lines: pitch, hero, highlights, install, build, command
line, config folder, license, and links into the website’s docs. It carries no feature catalog, so it changes
only when those facts do.
- Check (code):
README.mdis near 200 lines and links to the website’s docs instead of listing every feature. - Reference: Repository documents; Editora
docs/conventions.md#docs-in-the-same-pr.
- Check (code):
Pauta 4.1.0 · · Changelog · This page in the latest edition