Write Docs

write-docs

Tale's docs read as one narrator: a calm, opinionated peer who shipped a similar product and is telling a capable stranger how this one works — not selling, not hand-holding, not congratulating. Every page says what the thing is, who it's for, why it exists, then walks it. This skill owns structure and voice for the English source and the structural test suite that gates it (the check-by-check reference is [CHECKS.md](CHECKS.md)); cross-locale work — translated UI labels, per-locale grammar, loanwords — is the companion [write-translations](../write-translations/SKILL.md) skill.

When this applies

Editing or creating any page under [docs/](../../../docs/) (en/, de/, fr/), editing [docs/nav.json](../../../docs/nav.json), or touching the docs build under services/docs/. Editing a non-en page → read [write-translations](../write-translations/SKILL.md) too. Running or triaging the structural test suite → [CHECKS.md](CHECKS.md).

Write a note first

Invoke write-notes and record your answers to this form before you write the page:

• Page & audience: Describe the page or section, its tab (cloud / self-hosted / platform / develop), and its what / who / why.
• Verified claims: Describe which labels, defaults, routes, or limits you checked against source — and what you found, including anything that surprised you.
• Ripple: Describe which base locales (en / de / fr), nav entries, and screenshots this touches.
• Risks & unknowns: Describe where a claim might still be wrong or out of date, and how you'd confirm it.

The voice — see it first

| Version | Sample | Why it fails | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | Marketing soft | Simply click Save and you're all set! Feel free to add as many providers as you like. | "Simply", "all set", "Feel free to", !. | | First-person we | We recommend you click Save after configuring each provider, since we sync them in the background. | "we", missing why. | | Imperative naked | Click Save. | No why — what does Save do here? | | Tale voice | Click Save. The new provider is reachable from agents on the next request — there's no separate rollout step, and existing conversations keep their previous model binding. | Imperative, why present, no fluff. |

Three guardrails the voice always holds:

• Second person, informal — you / du / tu. Never we, the user, Sie, vous.
• Imperative for instructions — Run tale deploy, never You can run…, never Please run….
• Why before what — name the consequence (what it does, what breaks if you skip it), then the step.

Internalise the table; the strike lists catch the slips. The EN strike rules (simply, easy, seamless, …), the DE bureaucracy patterns, and the FR softeners live in test data at [packages/ui/src/i18n/tests/locales//voice.ts](../../../packages/ui/src/i18n/tests/locales/).

The rules

Five rules fail review. Three are also enforced by tests.

1. Docs ship with code. A PR that changes what a user sees, configures, or interacts with —

feature, setting, env var, API response, CLI flag, removal — updates the docs in every base locale (en, de, fr) in the same PR. Code without docs does not merge. Reviewer-caught.

1. Real opening, real closing. The prose between the frontmatter and the first

heading/list/table/fence is ≥ 2 sentences answering what / who / why; the last sub-section is named for what it does (## Build one, ## Where this fits), recaps the load-bearing idea in one paragraph, and sets up the next page in another. A ## Next over a bare link line is a stub. \_Enforced by [structure-opening.test.ts](../../../services/docs/tests/structure-opening.test.ts)

• [structure-closing.test.ts](../../../services/docs/tests/structure-closing.test.ts);\_ see the

rewrites in [EXAMPLES.md](EXAMPLES.md).

1. Labels match the shipped string — every translated UI label is character-for-character the

value in services/platform/messages/.json; no half-English Öffne **Settings**. The full contract is [write-translations](../write-translations/SKILL.md). Enforced by the i18n suite.

1. Claims are verified. Every label, env var, default, behaviour, route, limit, and permission is

checked against source before the page is done — labels in services/platform/messages/.json, routes/screens in services/platform/app/, backend behaviour in services/platform/convex/, defaults/ports in docker-compose.*.yml and the env loader. Voice covers how it reads; this covers whether it's true. Reviewer-caught.

1. One narrator. A page that drifts into marketing softening, first-person we, bureaucratic

passive, or status chatter fails — even if every other rule passes. Reviewer-caught.

Regional trees (the supported variant is de-CH, mirroring the UI-message variant) are sparse when one exists: override only pages whose wording genuinely differs from the base locale.

Patterns

The body is everything between the opening and closing:

• Prose is the default. A heading owns a paragraph, not a list. Lists are for 5+ parallel items.
• Tables for data with row-level identity. Code blocks lead with their effect.
• Walkthroughs go effect → location → action:
• ✗ Click Settings, then Members, then Invite member. This adds a person.
• ✓ To add a person to your organisation, open **Settings > Members** and click **Invite member**.

platform/ vs self-hosted/configuration/. platform/ is the UI — anything a user does inside the running app (Settings > …). self-hosted/configuration/ is server-side — config files (TALE_CONFIG_DIR/**), env vars, CLI, Docker. When a feature has both, platform/ describes only the UI path and links to the self-hosted reference for the file form. Never paste a JSON config snippet or env-var table into a platform/ page — it contradicts the Cloud reader's reality and belongs one tab over.

Seven page types cover docs/; the per-type shape contract, a pattern page, and the common failures live in [PLAYBOOKS.md](PLAYBOOKS.md). Where each page lives:

| Directory | Tab | Audience | | -------------- | ----------- | ------------------------------------------------------------------------------------------------------------- | | cloud/ | Cloud | Managed-SaaS readers — onboarding, billing, data residency, trust, compliance. | | self-hosted/ | Self-hosted | Operators running Tale on their own infrastructure, plus end users of those instances split by role. | | platform/ | Platform | Product feature reference. Identical for Cloud and Self-hosted. The single source of truth for every feature. | | develop/ | Develop | API consumers, webhook integrators, SDK users, source contributors. | | legal/ | (footer) | Privacy policy, terms of service, DPA. noindex: true. |

Before you call the page done

Tick every box, or N/A with a reason:

• [ ] Docs ship with the code — every base locale (en, de, fr) updated in the same PR for a user-visible change.
• [ ] Real opening (≥2 sentences: what / who / why) and a real closing — a named recap, not a ## Next stub.
• [ ] Every UI label matches the shipped string in services/platform/messages/.json — no half-English walkthroughs.
• [ ] Every claim verified against source — labels, env vars, defaults, routes, limits, permissions.
• [ ] One narrator — no marketing softening, first-person we, bureaucratic passive, or status chatter.
• [ ] The structural suite is green — bun run --filter @tale/docs test (see [CHECKS.md](CHECKS.md)).

Companion files

• [EXAMPLES.md](EXAMPLES.md) — read when writing an opening, closing, or walkthrough and you want to see what passing prose looks like.
• [PLAYBOOKS.md](PLAYBOOKS.md) — read when you know the page type (concept, tutorial, reference, …) and want its shape contract + common failures.
• [MECHANICS.md](MECHANICS.md) — read for frontmatter, filenames, headings, code blocks, tables, lists, Mermaid, and links.
• [SCREENSHOTS.md](SCREENSHOTS.md) — read before adding an image.
• [CHECKS.md](CHECKS.md) — read when running or triaging the structural docs test suite: every check, what it catches, and the fix-priority order.
• [WORKFLOW.md](WORKFLOW.md) — read before previewing locally or running the pre-PR suite.
• [write-translations](../write-translations/SKILL.md) — read before editing any non-en page.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tale-project
• Source: tale-project/tale
• License: MIT
• Homepage: https://tale.dev

Install and usage instructions live in the source repository linked above.