end-user-docs

# End-User Docs Writer Author guidance for public-facing, non-technical documentation in this repository. --- ## Use This Skill When - The task is writing or refining public user docs under `docs/`. - The audience is hosted end users and administrators, not developers. - The request is about wording quality, page structure, readability, or clarity. - You need to keep docs aligned with verified application behaviour and feature contracts. Do not use this skill for internal engineering material under `docs-internal/`. --- ## Primary Inputs (Order of Truth) Use repository sources in this order: 1. Verified product behaviour from code and tests for user-visible states, labels, and outcomes (for example report wording, CSV headers, priorities, and consent wording) 2. Applicable docs contract(s) under `specs/*/contracts/` for the active docs feature 3. Active docs feature specification artefacts under `specs/*/` (`spec.md`, `research.md`, `data-model.md`, `plan.md`) 4. Existing published docs content under `docs/` to preserve terminology and navigation consistency If sources conflict, follow the highest item in this list. For user-facing wording, current app behaviour always wins over stale spec or contract text; then update the stale planning artefact in the same change. --- ## Audience and Voice - Primary audience: non-technical hosted users. - Secondary audience: administrators reviewing permissions and privacy statements. - Tone: clear, calm, practical, and honest. - Style: short sentences, active voice, concrete actions. - Language: UK English only (for example, "organisation", "behaviour", "colour"). Avoid internal framing such as architecture details, implementation classes, deployment internals, or incident-runbook language. --- ## Content Rules For every page, ensure: - Plain-English explanations without jargon. - Steps are task-oriented and ordered. - The user can identify what to do next without needing source code. - Claims are grounded in verified behaviour, not guesses. - Example CSV data is illustrative and safe for public publication. Never include: - Secrets, credentials, tenant-sensitive values, or internal-only troubleshooting notes. - Instructions that belong in `docs-internal/`. - Statements that imply fixed deployment timing guarantees when only automatic publication is required. --- ## Required Coverage by Page When creating or reviewing public docs pages, validate the obligations defined in the active docs contract. For the current site structure, this typically includes: - `/`: purpose, audience, links to core guides. - `/getting-started`: hosted prerequisites, hosted app access, sign-in and consent expectations. - `/csv-format`: required `Task Name`, accepted fields, allowed priority values, safe examples, common mistakes. - `/import-workflow`: ordered workflow steps, preview versus execution, `Created` and `Reused or skipped` outcomes, manual goal follow-up note. - `/troubleshooting`: sign-in/consent, no groups found, CSV validation, duplicates, temporary API/throttling issues. - `/faq`: duplicates, existing plan import, goal handling, supported audience, data storage. - `/privacy-and-security`: Graph read/write scope at high level, no imported Planner/task data persistence, limited operational logs/telemetry, credential handling statement, delegated permissions summary. - `/self-hosted` (secondary): clearly labelled as secondary and not part of the hosted primary path. --- ## Writing Workflow 1. Confirm page goal, audience, and required sections. 2. Draft a concise outline with user tasks first. 3. Write content in plain UK English. 4. Cross-check all behaviour statements against repository sources. 5. Run a final quality pass: - remove jargon - simplify long sentences - verify links and navigation - confirm public-only content boundary --- ## Done Criteria Treat a docs update as complete only when all are true: - Contract obligations for the page are satisfied. - Wording is understandable to non-technical users. - UK English is consistent. - Links are valid and navigation is not broken. - Content contains no internal-only details.