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:
1 parent
bb141cdffc
commit
20754f15e2
1 file changed
+27
-3
@@ -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
|
||||||
|
|||||||
Reference in new issue
Block a user