From 20754f15e29e4002d8e65946ad6d368056f7af5c Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Nov 2026 13:40:34 -0500 Subject: [PATCH] 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). --- docs/developer/writing-ui-docs.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/docs/developer/writing-ui-docs.md b/docs/developer/writing-ui-docs.md index b7ec9aac..b9c773c7 100644 --- a/docs/developer/writing-ui-docs.md +++ b/docs/developer/writing-ui-docs.md @@ -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