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
|
||||
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
|
||||
|
||||
Reference in new issue
Block a user