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
consistently. The reader is assumed to know books, while the app's own
words are the only technical vocabulary allowed.
- **Developer and Administration sections — tone is a separate discussion,
not yet decided.** Write them plainly and hand-off-rich as well; do not
import opinions about their voice until that pass happens.
- **Administration (`docs/admin/`) — plain language, one layer deeper.**
Same bones as the user docs: task-first, what to click for what, exact
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
@@ -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
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
The filter documentation (and the older filtering overview) is hands-off