docs(standard): admin tier defined; promises require owner approval

Two additions to the screenshot-free writing standard, both owner-
ruled during the admin-docs planning session:

- Tone by audience gains the Administration tier, ending the 'not yet
  decided' limbo for admin docs: plain language like the user docs, plus
  what every control actually does (semantics, cost, consequences)
  before the reader clicks, and per-setting what/does/means/range
  coverage. Calibration in one line: user = what you see, admin = what
  it does, developer = how it works. The Developer section keeps its
  separate tone discussion for the deferred dev-docs pass.

- New 'Promises need approval' section: no coming-soon / under-
  consideration / future-release language anywhere without the owner's
  explicit approval of that exact promise; speculative text found in the
  docs is reported, never quietly kept or quietly deleted. Provenance
  recorded (the 2026-11-02 device-promise removals; the Operations
  placeholders knowingly kept).
This commit is contained in:
John O'Keefe committed 2026-11-02 13:40:34 -05:00
1 parent bb141cdffc
commit 20754f15e2
1 file changed
+27 -3
+27 -3
View File
@@ -74,9 +74,21 @@ make the page followable even if that label is renamed next week.
genuinely needs (say, *rule*) is explained once, in place, then used genuinely needs (say, *rule*) is explained once, in place, then used
consistently. The reader is assumed to know books, while the app's own consistently. The reader is assumed to know books, while the app's own
words are the only technical vocabulary allowed. words are the only technical vocabulary allowed.
- **Developer and Administration sections — tone is a separate discussion, - **Administration (`docs/admin/`) — plain language, one layer deeper.**
not yet decided.** Write them plainly and hand-off-rich as well; do not Same bones as the user docs: task-first, what to click for what, exact
import opinions about their voice until that pass happens. quoted labels. Added: every control also states what the click *actually
does* — semantics, cost, and consequences — before the reader clicks it.
The canonical example: **Force Rescan All Libraries** re-reads and
re-extracts every file and recomputes hashes, while the other scan
buttons are shallow scans that skip unchanged files — an admin should
know that before clicking, not after. Every setting states what it is,
what it does, what it means when that is confusing, and its valid range.
No API-client detail: request and response schemas live in the developer
docs. The calibration in one line: **user = what you see, admin = what
it does, developer = how it works.**
- **Developer section — tone is a separate discussion, not yet decided.**
Write it plainly and hand-off-rich as well; do not import opinions about
its voice until that pass happens.
## Generate what has a registry ## Generate what has a registry
@@ -109,6 +121,18 @@ resolve, links still resolve, affected pages re-read against the new
surface. The pattern layers keep users oriented between audits; the audit surface. The pattern layers keep users oriented between audits; the audit
keeps layers 3–5 honest. keeps layers 3–5 honest.
## Promises need approval
Docs never promise future behavior on the owner's behalf. No "coming soon",
"under consideration", "in a future release", or any other forward-looking
commitment gets written without the owner explicitly approving that exact
promise — and anything speculative found in the docs gets reported, not
quietly kept and not quietly deleted. (Rule origin, 2026-11-02: the owner
ruled out "Kindle and reMarkable are under consideration" and a "Custom
Calibre Columns (Future)" section — no such plans existed — while the
Operations guide's pre-existing "Coming Soon" placeholders were reported
and knowingly kept for the future operations-docs pass.)
## What this does not replace ## What this does not replace
The filter documentation (and the older filtering overview) is hands-off The filter documentation (and the older filtering overview) is hands-off