docs-writing

Writing Stigmer's documentation

docs/STYLE.md holds the mechanics (headings, code blocks, MDX components, the classification contract, the medium rule) and docs/vocabulary.md holds what Stigmer is and who it is for, every term and the five writing contexts. Neither is restated here. This skill holds the doctrine those two apply: why the rules are what they are, and the judgement calls a page needs that no lint can make. The package guide (docs/AGENTS.md) carries the laws in one line each.

Match the register to the reader

Every page speaks to one reader: the developer adding agents to their product. Any sentence that says what Stigmer is uses the words in docs/vocabulary.md, "What Stigmer is, and who it is for", and its examples are jobs done inside a customer's product, never a chat and never code.

docs/vocabulary.md defines five contexts (sales site, quickstart and tutorials, concepts and how-to, reference and SDK, README), each with its own audience and register. Identify the context before writing a sentence, then calibrate.

• When the context is unclear, write for the least technical reader in the audience. Plain language is always safe; unnecessary jargon never is.
• On the sales site and in introductory docs: replace jargon with plain words ("definition file", not "declarative manifest"; "keeps running even if something crashes", not "durable execution with checkpoint recovery"); when a term such as API or YAML is unavoidable, explain it in the same sentence. Analogies from the reader's own stack (their database, their sign-in provider, their job queue) are welcome where they say where Stigmer sits; never an analogy to a tool the reader may not run, such as Kubernetes or Temporal.
• In reference and SDK docs: precise technical language, exact field names, proto message types and CLI flags; do not re-explain what earlier pages taught.
• In architecture and contributor docs, references to Kubernetes, Docker and the like are appropriate; the audience lives there.
• Stigmer's own terms are proper nouns used consistently. Never a synonym.

Choose the medium with the rule, not by preference

The rule is in docs/STYLE.md ("Classify every page"), applied in order, first yes wins. Two doctrines sit behind it:

• Motion is for demonstration. An animated tour is reserved for a flow whose timing or cause-and-effect is the lesson. A reader working through a quickstart wants to stop, compare their screen with ours and scroll back; an animated tour makes all of that awkward. Getting-started journeys and console procedures are screenshot journeys paced by the reader.
• The text fallback is a hard requirement. The docs are read through three channels: the rendered site, the markdown exports (llms-full.txt and the per-page .md files) and the Copy-as-Markdown button. An embed is invisible in the last two; it passes through as a dangling tag. Every visual therefore contributes text to the exports (per-step prose, alt text, or the Mermaid source itself), and the prose around an embed carries the information on its own. A Screen contributes its alt text and a link to its picture: the export turns the tag into a markdown image. A Live contributes its alt text, linked to the demo. A TerminalRecording contributes its alt text and its last frame as text. A Diagram contributes the text it stands for, kept beside its drawing in site/src/components/visuals/: the export turns the tag into that text. A concept page's own system picture is a Diagram, drawn in the site's language; every other diagram is Mermaid (docs/STYLE.md, "Diagrams").

Screens come from the visual suite

A page shows a screen only as a picture stigmer's visual suite draws, so the picture fails a test the moment the product's look moves and is redrawn in the same pull request. To show one:

1. Put every value the page prints that the picture shows (a name, a message, a host) in the page's example in test/visual/src/docs-examples.ts. The scene draws from it, and the site's docs-screens test fails when the page and the file disagree, so change both together.
2. Add an entry to test/visual/src/shown.ts: a gallery scene from test/visual/src/catalog.ts, the size it is drawn at, and a clip around the part of the screen the step acts on. A screen the gallery does not draw yet needs its scene first (test/visual/README.md, "Add a scene"); a form the step fills, or a tab or menu it opens, is reached by the scene's acts.
3. make test-visual UPDATE=1 mints the picture; review it like any screenshot.
4. Embed it with <Screen name="…" alt="…" /> right after the step it shows.

Picture the steps a reader acts on or must recognise, cropped to that part of the screen; navigation and other sites' screens (Slack's, Meta's, an OAuth provider's) stay prose. A hand-captured screenshot rots with no signal, so it is never added, not even as a placeholder. make check-docs-inventory holds every still and screenshot-journey page to at least one <Screen> and every other page to none; a page still waiting for its pictures is listed, with its reason, in OWED_PICTURES (site/src/lib/docs-inventory.ts).

Live demos come from the visual suite too

An interactive page embeds the kit itself, live: <Live name="…" alt="…" /> frames a gallery scene in the gallery's docs mode, where a scripted server answers a reader's send, approval and Stop with one scripted turn (the kit's scenario catalogue holds it). The demos are listed in test/visual/src/live.ts; a scene the list lacks gets its entry there (test/visual/README.md, "Live demos"), and the visual suite's live spec drives it. The theming page's <ThemePlayground /> is one of them, with the code to copy. Never build a demo for a page: the docs had one until it went stale with every refactor, and the gallery is drawn by the code the screenshot check already holds.

Terminal recordings come from the terminal kit

An animated-tour page about the terminal plays a recording: <TerminalRecording name="…" alt="…" />. A recording is the terminal kit's SessionView drawn over a story of the scenario catalogue one event at a time, listed in sdk/ink/src/recordings.ts and held, frame by frame, by the kit's test (sdk/ink/src/__tests__/recordings.test.tsx), so a change to the terminal's look fails there and redraws the docs in the same pull request. A new recording gets its entry there and is minted with npx vitest run -u in sdk/ink. Never record a real terminal for a page: its timing varies and it drifts with no test noticing. An animated-tour page with nothing to play stays prose, code and diagrams until it has a recording.

Alt text describes the screen

Alt text is written for a reader who cannot see the image: it describes what the image shows, not what the reader should feel about it, and it is authored in the MDX beside the image. It is also what the markdown exports carry in the image's place.

Tutorials and learning paths

For any content where pages form a sequence:

• Narrative continuity. Each page opens on what the reader accomplished on the previous page and closes by motivating the next with a concrete, functional reason. Test: read only the first and last paragraph of each page; can you reconstruct the order without the sidebar?
• Aha-moment design. Each tutorial names one moment where the reader sees something work. State it in "What you'll build", deliver it when the reader runs the command, reinforce it in "What just happened". Test: point to the exact step where the reader's screen changes in a way that proves the concept. If the payoff is only intellectual, the tutorial is an explanation in disguise.
• One new concept per page. Defer what the reader does not need yet.
• Implicit defaults. Use the platform's sensible default without asking the reader to configure anything; introduce configuration when there is a reason to customise.
• The bridge. Every page in a sequence ends with a "Next step" that answers two questions: what can the reader not do yet, and what will the next page teach? The motivation is a gap the reader can feel, never navigational. Good: "Your agent made the variance report, but it can't reach your customers' ledgers yet. Let's connect it." Bad: "Continue to the next tutorial."
• Entry-point ordering, path convergence and prerequisite chains belong to the information architecture; a page author does not decide path structure.

Code examples compile, or say why they cannot

Every TypeScript, Go, Python and Java block is compiled against the SDK it shows (docs/STYLE.md, "Code examples compile", has the mechanics). Write each one as a reader will paste it:

• Show the imports. A page whose examples share them shows them once in a visible prelude block per language; a single example imports in place.
• Take as given only the client: stigmer or client in TypeScript, client and ctx in Go, client in Python and Java. A name the page's prose introduces (a user the previous step signed in, an accountId the last call returned) is declared in the block's hidden setup, above // ---cut--- (# ---cut--- in Python). The setup holds declarations and the imports they alone need, never an import the visible code uses and never logic the reader needs; if it carries meaning, it moves into the body. The prose still names the given, as it always has.
• Use the SDK's real names and types: the proto message a method takes, an enum value rather than its string, the field a client exposes. The resource reference pages show each language's form.
• An example that returns a value is the function it belongs to.
• Mark a block no-compile="reason" only when it cannot compile and should not: pseudo-code, a sketch with arguments elided, a wrong value shown beside a right one. The reason says which.

The gate's list of blocks allowed to fail today may only shrink; never add to it.

Reference pages generated from protos

SDK reference pages are generated from the proto schemas; the generator lives under tools/codegen/ and the comment convention it reads is owned by tools/codegen/src/internalcomment/internalcomment.ts (the apis/AGENTS.md laws state it). Proto comments serve proto readers; the hand-written overview file in the docs folder beside a resource's protos (for example apis/ai/stigmer/agentic/agent/docs/overview.md) serves SDK users and becomes the reference page's first section verbatim. Do not make one text serve both audiences with markers or keywords.

An overview file is written in the reference register and the Diátaxis reference type: two or three sentences on what the resource is and configures, then one minimal, representative YAML example in a standard fenced block (every YAML block under docs/ is contract-validated, so it must apply as written). No frontmatter, no metadata, no duplication of what the generated Methods and Types sections already say.

What to refuse

• Documentation that requires the reader to already understand the thing being documented.
• A page added, moved or deleted without its classification entry changing in the same commit.
• A hand-captured screenshot, even as a placeholder.
• An animated tour for content the reader works through at their own pace.
• A visual that leaves the markdown exports with nothing.
• On the sales site or in introductory docs, an analogy to a tool the reader may not run.
• An example from coding work (pull-request review, code generation).
• Filler ("it should be noted that", "it is important to understand").
• Two Diátaxis types on one page.
• A measured Stigmer-versus-Claude comparison, in a table, in prose or through a fixture. The harness benchmark (make benchmark-harnesses, test/conformance) is an internal instrument and this refusal is its rule's home: an Agent performs best in the harness and models built for it, so a generic comparison on a handful of prompts tells a reader nothing about their Agent, and the platform's own evaluation tooling is where they measure it. A page explains how the harnesses differ and never quotes a measurement between them.