Documentation writing
A developer arrives with a job to do, not with an interest in our repository
structure. Start from that job: what did they try, what stopped them, and what
would let them know they succeeded? Use Diátaxis
as a compass for each page's primary purpose, not a purity test. This skill
governs content and reader journeys; the owning repository governs page
placement, navigation, and rendering.
Use the specialists at their boundary
Read this skill to plan the reader journey, then read
cratis-engineering-docs-authoring to draft from product evidence,
cratis-technical-examples to verify code, commands, configuration and output,
and cratis-llm-friendly-documentation when discovery or exported representations
are involved. Read cratis-writing-voice-and-cadence before revising existing
prose. Skill availability is not evidence that its instructions were read.
Before drafting or revising explanations beside examples, read and apply
Explaining code.
Use its worked transformations to choose the detail that carries the explanation;
use its multi-client guidance before choosing shared prose, tabs or separate
procedures. Read the resulting paragraphs for connected reasoning, not just
coverage of accuracy questions.
The documentation rule owns Platform naming and
product-claim constraints; do not turn an umbrella label into a dependency on
all components.
Classify before writing
Determine which quadrant the page belongs to before drafting:
| Type |
Orientation |
Analogy |
When to use |
| Tutorial |
Learning |
A lesson |
Guide a newcomer step-by-step to a successful first outcome |
| How-to guide |
Problem-solving |
A recipe |
Show an experienced user how to accomplish a specific task |
| Reference |
Information |
A dictionary |
Describe the technical machinery — APIs, attributes, configuration |
| Explanation |
Understanding |
A discussion |
Clarify why something works the way it does, trade-offs, architecture |
Rules per type:
- Tutorial — lead a newcomer through one realistic, threaded outcome.
Each step has a visible result. Briefly explain the invisible effect of a
step, then link to an explanation for deeper theory; do not interrupt the
lesson with a reference dump. Show the smallest safe configuration that
runs before presenting options: bind local services to loopback, label
development credentials as such, and put host and configuration
alternatives in linked how-to guides. Make the first snippet the convention
path, with no registration or wiring a convention already does, then name
what the framework did that the reader cannot see.
- How-to guide — assume competence. State the goal, list prerequisites,
give the steps and a completion check. Explain necessary concepts, effects,
and recovery beside the step; link sustained teaching elsewhere.
- Reference — exhaustive within its declared scope and terse. For each
public option or API, cover type, required/optional status, default, valid
values, return behavior, errors and compatibility where applicable. State
scope and link to a working usage example; do not turn it into a lesson.
- Explanation — discuss concepts, trade-offs, and design decisions. Short
steps or examples can make an effect concrete without becoming a full
procedure. Diagrams are welcome when they clarify a relationship.
A brief prerequisite or explanation may serve the main journey. If a reader
also needs an exhaustive lookup, link a reference page rather than burying it
in the lesson. Resolve routine audience or type choices from the request
and neighboring pages; ask only when the alternatives change the outcome.
Work from the reader outward
- Find the authored source, neighboring pages, existing user entry points,
and current product behavior. Do not edit generated site copies. Identify
whether the reader is new, migrating, troubleshooting, or looking up an API.
- Identify the question the reader came with and what would answer it.
Let the title and opening serve that task: a tutorial can introduce a concrete
problem and payoff; a reference entry can state the requested contract directly.
Include context when it helps the reader act or understand.
- Trace a short route from that page to one clear 'start here' entry,
targeted recipes, and exact reference. Give different languages or hosts
their own procedures when a shared path cannot be run as written. A
'coming from X' bridge should map familiar concepts to the new workflow,
not replace it. When comparison helps readers choose among backends, use a
"how the backends differ" table near the start for relevant distinctions:
identity source, id and response wire types, default authorization, live versus
snapshot queries, and unsupported features with their tracking issue when
available. Across a series, keep backend limitations in one table on the series index
and link it, while keeping action-changing differences beside the affected
example. Keep essential shared context and warnings outside tabs. Check each
client independently: shared concepts do not imply shared setup, semantics or
support. Give divergent setup its own coherent procedure.
- Link required tools to their canonical installation procedures before the
first command. For cross-product prerequisites, use a verified public route;
a named Markdown reference is defined on this same page, not in another
repository. Do not revive DocFX
xref: symbols or duplicate another
product's setup recipe. See the documentation formatting rule for syntax.
- Draft in workflow order. For a tutorial, use one working domain throughout
and show what to run and what appears. Recap only when a longer thread needs
reorientation before another concept. For a how-to, keep only what the
specific task needs. Link out for details.
Many Cratis readers are adopting a paradigm (event sourcing, event
modeling, vertical slices), not only a tool: link the explanation from the
start route, but let the reader reach a first success before the theory.
- Read the rendered page as a newcomer: could they find it, begin without
hidden prerequisites, recover from a common mistake, and recognize success?
For a new or materially changed journey, read and use
fresh-context reader review. An author's
reread is useful but is not independent reader evidence. Check claims,
examples, accessibility, links, and the owning gates separately.
Use support questions and user feedback as evidence: ask what they searched
for, where they looked, and which step failed. Repair the entry link, wording,
or example as appropriate; adding another FAQ entry alone may not fix discovery.
The docs are also the answer surface for Prompter and Chronicle MCP, so treat
a repeated question as a signal to investigate the page, its entry route, or
the product behavior behind it. Reduce a report to the page and the
sentence-level change the reader expected. Make an in-scope fix when the
evidence supports one; otherwise report the gap and suggest an issue, opening
one only when asked.
Cratis site specifics lists the signals Prompter
actually records.
Writing style
The voice is direct, practical, and opinionated — an experienced colleague
explaining something to a capable developer, confident but never condescending.
- Active voice, present tense. "Chronicle appends the event", not "The
event is appended by Chronicle."
- Address the reader when giving an action: "You configure…". In reference
and explanation, let the API or component be the subject when that is clearer.
- Lead with the reader's problem and payoff. Explain why a capability
matters before its configuration, except in a terse how-to or reference.
- Develop explanations in connected paragraphs. Use headings to locate them,
lists for real steps, and tables for comparisons; do not fragment reasoning
into a series of labeled boundaries.
- Focus on public behavior. Explain what happens behind an example when the
reader needs it to understand the result, without turning the page into an
internal implementation manual.
- Teach the intended idioms: show the conventional shape of a solution and
explain why a tempting non-idiomatic approach causes trouble. Distinguish a
framework requirement from a house convention; avoid making a workaround the
first example a newcomer copies.
- State limitations, maturity, compatibility, and when the simpler approach
is preferable. Link to third-party docs instead of retelling them. Say that
an experimental or preview surface is experimental on its own first screen;
a sidebar link or published guide does not tell the reader.
- Use a Mermaid diagram where
architecture, a sequence, or state transitions are clearer drawn than
told. A diagram replaces topology prose; it does not decorate a page.
- Vary sentence and paragraph rhythm; avoid templated openings and filler.
A voice edit must never weaken a technical caveat or invent experience.
- American English only:
color not colour, behavior not behaviour,
organize not organise, initialize not initialise.
AI-assisted drafting
Use AI to find gaps, compare terminology and review a draft, but do not let
plausible generated prose decide what problem the product solves. Ground the
reader journey in observed use cases and have the owning maintainer review
structural changes. A style pass cannot establish technical correctness.
Do not rewrite an entire corpus into one repeated template.
An AI-drafted narrative is a first draft, not a finished page. Give the model
the reader, the scenario, the terminology and the source evidence up front;
then revise the result against that evidence and the
cratis-writing-voice-and-cadence constructions before it ships. Tell the
reviewer the narrative was AI-drafted (in the review request, a PR comment or
the commit message, never in the PR description, which is published as the
release note) so they read it as prose, not only as a diff.
For machine-readable delivery and retrieval checks, use
cratis-llm-friendly-documentation; publishing llms-full.txt alone does
not prove that an assistant can find the right page or cite it accurately.
Examples and maintenance
Use cratis-technical-examples to choose between a short verified
illustration and a snippet extracted from compiling, tested sample source.
Never transcribe an API from memory, hand-translate an unsupported client, or
claim a pasted block is runnable when it requires unstated setup. Show the
command and observable output for a substantial walkthrough.
Adding a backend or client to a product also changes pages the product's own
checks don't scan, such as cross-product and site-level pages. Search them for
single-language claims ("in C#", C#-only APIs presented as universal) and for
series indexes whose description, reading order or production claims no longer
hold.
Edit the authored file, never a synced copy. The Cratis site derives each
product page's edit link from that source path, so don't hand-author
editUrl in product frontmatter. Recheck examples against the supported
version when that version changes. A review of docs is not complete just
because the site builds: syntax and behavior are different checks.
A page is done for this change, not finished forever. Expect to revisit its
wording, structure and examples as readers hit them.
Guide the next useful action
Give enough context to choose a relevant path, then place each prerequisite
beside its first use. Distinguish optional integration from required setup.
For a procedure, show a small meaningful action, its visible result and any
invisible effect before linking the next task or exact reference. Develop the
explanation from that action using Explaining code, rather than publishing
a separate list of responsibilities, defaults and limits. Link
source-backed recovery at likely failure points; do not invent error messages
or recovery commands. Keep lookup pages concise and explanations purpose-led,
not a compulsory tutorial template.
For Astro pages, deliberately choose supported presentation from
the site guide when it helps the task: ordered
steps, consequential callouts, peer-choice cards, or diagrams and code emphasis.
A prose-only pass can miss useful aids; uniform decoration can obscure them.
Preserve semantic order, accessibility and text/AI export meaning. Select the
relevant perspectives in reader review,
proportionately, without requiring a reviewer for every lens.
Cratis platform specifics
Read Cratis site specifics before writing a
Cratis product page. It covers the teaching components (YouWillLearn,
Recap, client tabs, including on site-owned pages), the variant-docs audit,
maturity and preview labeling, cross-product compatibility, the Prompter
feedback signal, and who decides page structure.
Contextual awareness
- Read the existing documentation around the page you are writing first, and
match its tone, style, and terminology. If it is "event source" there, it is
"event source" everywhere.
- Do not copy content from existing pages unless explicitly asked; link
instead.
- Do not fabricate URLs or version numbers — link only to resources you can
verify exist.
Keep editorial research private
Keep stylistic influences and editorial research in private working notes,
not documentation, GitHub issues, pull requests, release notes or other public
text. Develop each reader journey from Cratis product evidence rather than
copying another project's structure or claims. This does not remove third-party
integration names, necessary API identifiers or links readers need to use them.
Completion checklist
A page is done when:
- The page has a deliberate primary purpose; short supporting context helps
the reader proceed, while substantial digressions link to their own pages.
- The audience and their goal were identified before writing, and the first
screen serves that goal. The first working path needs no unexplained setup
or up-front choice among configuration alternatives, and it is safe to run
on a developer machine as written.
- Examples teach intended idioms and identify relevant traps without turning
a tutorial into an exhaustive list of alternatives.
- Examples are source-verified, complete at their stated scope, and show a
checkable result; longer examples come from compiling sample or spec source.
Explanations of what happened match the backend the reader built.
- The entry point, terminology, and next-step links fit the surrounding docs.
- A new or materially changed journey has fresh-context reader evidence, or
explicitly reports that review as unavailable. Missing steps and guessed
prerequisites are gaps, not reader success.
- All internal links resolve; all external links are real.
- Mermaid blocks are syntactically valid.
- The file ends with a single trailing newline.
1---2name: cratis-documentation-writing-23description: Use when planning a Cratis documentation reader journey, choosing a page's purpose or reviewing its structure. Not for example execution, release notes or publication; use the corresponding specialist.4license: MIT5metadata:6 source: https://skillmd.com/skills/cratis/cratis-documentation-writing-27 cratis-hint-paths: "**/Documentation/**/*.{md,mdx}"8---910# Documentation writing1112A developer arrives with a job to do, not with an interest in our repository13structure. Start from that job: what did they try, what stopped them, and what14would let them know they succeeded? Use [Diátaxis](https://diataxis.fr/)15as a compass for each page's primary purpose, not a purity test. This skill16governs content and reader journeys; the owning repository governs page17placement, navigation, and rendering.1819## Use the specialists at their boundary2021Read this skill to plan the reader journey, then read22**cratis-engineering-docs-authoring** to draft from product evidence,23**cratis-technical-examples** to verify code, commands, configuration and output,24and **cratis-llm-friendly-documentation** when discovery or exported representations25are involved. Read **cratis-writing-voice-and-cadence** before revising existing26prose. Skill availability is not evidence that its instructions were read.27Before drafting or revising explanations beside examples, read and apply28[Explaining code](../cratis-engineering-docs-authoring/references/explaining-code.md).29Use its worked transformations to choose the detail that carries the explanation;30use its multi-client guidance before choosing shared prose, tabs or separate31procedures. Read the resulting paragraphs for connected reasoning, not just32coverage of accuracy questions.33The [documentation rule](../../rules/documentation.md) owns Platform naming and34product-claim constraints; do not turn an umbrella label into a dependency on35all components.3637## Classify before writing3839Determine which quadrant the page belongs to before drafting:4041| Type | Orientation | Analogy | When to use |42| --- | --- | --- | --- |43| **Tutorial** | Learning | A lesson | Guide a newcomer step-by-step to a successful first outcome |44| **How-to guide** | Problem-solving | A recipe | Show an experienced user how to accomplish a specific task |45| **Reference** | Information | A dictionary | Describe the technical machinery — APIs, attributes, configuration |46| **Explanation** | Understanding | A discussion | Clarify *why* something works the way it does, trade-offs, architecture |4748Rules per type:4950- **Tutorial** — lead a newcomer through one realistic, threaded outcome.51 Each step has a visible result. Briefly explain the invisible effect of a52 step, then link to an explanation for deeper theory; do not interrupt the53 lesson with a reference dump. Show the smallest *safe* configuration that54 runs before presenting options: bind local services to loopback, label55 development credentials as such, and put host and configuration56 alternatives in linked how-to guides. Make the first snippet the convention57 path, with no registration or wiring a convention already does, then name58 what the framework did that the reader cannot see.59- **How-to guide** — assume competence. State the goal, list prerequisites,60 give the steps and a completion check. Explain necessary concepts, effects,61 and recovery beside the step; link sustained teaching elsewhere.62- **Reference** — exhaustive within its declared scope and terse. For each63 public option or API, cover type, required/optional status, default, valid64 values, return behavior, errors and compatibility where applicable. State65 scope and link to a working usage example; do not turn it into a lesson.66- **Explanation** — discuss concepts, trade-offs, and design decisions. Short67 steps or examples can make an effect concrete without becoming a full68 procedure. Diagrams are welcome when they clarify a relationship.6970A brief prerequisite or explanation may serve the main journey. If a reader71also needs an exhaustive lookup, link a reference page rather than burying it72in the lesson. Resolve routine audience or type choices from the request73and neighboring pages; ask only when the alternatives change the outcome.7475## Work from the reader outward76771. Find the authored source, neighboring pages, existing user entry points,78 and current product behavior. Do not edit generated site copies. Identify79 whether the reader is new, migrating, troubleshooting, or looking up an API.802. Identify the question the reader came with and what would answer it.81 Let the title and opening serve that task: a tutorial can introduce a concrete82 problem and payoff; a reference entry can state the requested contract directly.83 Include context when it helps the reader act or understand.843. Trace a short route from that page to one clear 'start here' entry,85 targeted recipes, and exact reference. Give different languages or hosts86 their own procedures when a shared path cannot be run as written. A87 'coming from X' bridge should map familiar concepts to the new workflow,88 not replace it. When comparison helps readers choose among backends, use a89 "how the backends differ" table near the start for relevant distinctions:90 identity source, id and response wire types, default authorization, live versus91 snapshot queries, and unsupported features with their tracking issue when92 available. Across a series, keep backend limitations in one table on the series index93 and link it, while keeping action-changing differences beside the affected94 example. Keep essential shared context and warnings outside tabs. Check each95 client independently: shared concepts do not imply shared setup, semantics or96 support. Give divergent setup its own coherent procedure.974. Link required tools to their canonical installation procedures before the98 first command. For cross-product prerequisites, use a verified public route;99 a named Markdown reference is defined on this same page, not in another100 repository. Do not revive DocFX `xref:` symbols or duplicate another101 product's setup recipe. See the documentation formatting rule for syntax.1025. Draft in workflow order. For a tutorial, use one working domain throughout103 and show what to run and what appears. Recap only when a longer thread needs104 reorientation before another concept. For a how-to, keep only what the105 specific task needs. Link out for details.106 Many Cratis readers are adopting a paradigm (event sourcing, event107 modeling, vertical slices), not only a tool: link the explanation from the108 start route, but let the reader reach a first success before the theory.1096. Read the rendered page as a newcomer: could they find it, begin without110 hidden prerequisites, recover from a common mistake, and recognize success?111 For a new or materially changed journey, read and use112 [fresh-context reader review](references/reader-review.md). An author's113 reread is useful but is not independent reader evidence. Check claims,114 examples, accessibility, links, and the owning gates separately.115116Use support questions and user feedback as evidence: ask what they searched117for, where they looked, and which step failed. Repair the entry link, wording,118or example as appropriate; adding another FAQ entry alone may not fix discovery.119The docs are also the answer surface for Prompter and Chronicle MCP, so treat120a repeated question as a signal to investigate the page, its entry route, or121the product behavior behind it. Reduce a report to the page and the122sentence-level change the reader expected. Make an in-scope fix when the123evidence supports one; otherwise report the gap and suggest an issue, opening124one only when asked.125[Cratis site specifics](references/cratis-site.md) lists the signals Prompter126actually records.127128## Writing style129130The voice is **direct, practical, and opinionated** — an experienced colleague131explaining something to a capable developer, confident but never condescending.132133- **Active voice, present tense.** "Chronicle appends the event", not "The134 event is appended by Chronicle."135- Address the reader when giving an action: "You configure…". In reference136 and explanation, let the API or component be the subject when that is clearer.137- **Lead with the reader's problem and payoff.** Explain why a capability138 matters before its configuration, except in a terse how-to or reference.139- Develop explanations in connected paragraphs. Use headings to locate them,140 lists for real steps, and tables for comparisons; do not fragment reasoning141 into a series of labeled boundaries.142- Focus on public behavior. Explain what happens behind an example when the143 reader needs it to understand the result, without turning the page into an144 internal implementation manual.145- Teach the intended idioms: show the conventional shape of a solution and146 explain why a tempting non-idiomatic approach causes trouble. Distinguish a147 framework requirement from a house convention; avoid making a workaround the148 first example a newcomer copies.149- State limitations, maturity, compatibility, and when the simpler approach150 is preferable. Link to third-party docs instead of retelling them. Say that151 an experimental or preview surface is experimental on its own first screen;152 a sidebar link or published guide does not tell the reader.153- Use a [Mermaid](https://mermaid-js.github.io/mermaid/#/) diagram where154 architecture, a sequence, or state transitions are clearer drawn than155 told. A diagram replaces topology prose; it does not decorate a page.156- Vary sentence and paragraph rhythm; avoid templated openings and filler.157 A voice edit must never weaken a technical caveat or invent experience.158- **American English only**: `color` not `colour`, `behavior` not `behaviour`,159 `organize` not `organise`, `initialize` not `initialise`.160161## AI-assisted drafting162163Use AI to find gaps, compare terminology and review a draft, but do not let164plausible generated prose decide what problem the product solves. Ground the165reader journey in observed use cases and have the owning maintainer review166structural changes. A style pass cannot establish technical correctness.167Do not rewrite an entire corpus into one repeated template.168169An AI-drafted narrative is a first draft, not a finished page. Give the model170the reader, the scenario, the terminology and the source evidence up front;171then revise the result against that evidence and the172**cratis-writing-voice-and-cadence** constructions before it ships. Tell the173reviewer the narrative was AI-drafted (in the review request, a PR comment or174the commit message, never in the PR description, which is published as the175release note) so they read it as prose, not only as a diff.176177For machine-readable delivery and retrieval checks, use178**cratis-llm-friendly-documentation**; publishing `llms-full.txt` alone does179not prove that an assistant can find the right page or cite it accurately.180181## Examples and maintenance182183Use **cratis-technical-examples** to choose between a short verified184illustration and a snippet extracted from compiling, tested sample source.185Never transcribe an API from memory, hand-translate an unsupported client, or186claim a pasted block is runnable when it requires unstated setup. Show the187command and observable output for a substantial walkthrough.188189Adding a backend or client to a product also changes pages the product's own190checks don't scan, such as cross-product and site-level pages. Search them for191single-language claims ("in C#", C#-only APIs presented as universal) and for192series indexes whose description, reading order or production claims no longer193hold.194195Edit the *authored* file, never a synced copy. The Cratis site derives each196product page's edit link from that source path, so don't hand-author197`editUrl` in product frontmatter. Recheck examples against the supported198version when that version changes. A review of docs is not complete just199because the site builds: syntax and behavior are different checks.200201A page is done for this change, not finished forever. Expect to revisit its202wording, structure and examples as readers hit them.203204## Guide the next useful action205206Give enough context to choose a relevant path, then place each prerequisite207beside its first use. Distinguish optional integration from required setup.208For a procedure, show a small meaningful action, its visible result and any209invisible effect before linking the next task or exact reference. Develop the210explanation from that action using **Explaining code**, rather than publishing211a separate list of responsibilities, defaults and limits. Link212source-backed recovery at likely failure points; do not invent error messages213or recovery commands. Keep lookup pages concise and explanations purpose-led,214not a compulsory tutorial template.215216For Astro pages, deliberately choose supported presentation from217[the site guide](references/cratis-site.md) when it helps the task: ordered218steps, consequential callouts, peer-choice cards, or diagrams and code emphasis.219A prose-only pass can miss useful aids; uniform decoration can obscure them.220Preserve semantic order, accessibility and text/AI export meaning. Select the221relevant perspectives in [reader review](references/reader-review.md),222proportionately, without requiring a reviewer for every lens.223224## Cratis platform specifics225226Read [Cratis site specifics](references/cratis-site.md) before writing a227Cratis product page. It covers the teaching components (`YouWillLearn`,228`Recap`, client tabs, including on site-owned pages), the variant-docs audit,229maturity and preview labeling, cross-product compatibility, the Prompter230feedback signal, and who decides page structure.231232## Contextual awareness233234- Read the existing documentation around the page you are writing first, and235 match its tone, style, and terminology. If it is "event source" there, it is236 "event source" everywhere.237- Do not copy content from existing pages unless explicitly asked; link238 instead.239- Do not fabricate URLs or version numbers — link only to resources you can240 verify exist.241242## Keep editorial research private243244Keep stylistic influences and editorial research in private working notes,245not documentation, GitHub issues, pull requests, release notes or other public246text. Develop each reader journey from Cratis product evidence rather than247copying another project's structure or claims. This does not remove third-party248integration names, necessary API identifiers or links readers need to use them.249250## Completion checklist251252A page is done when:253254- The page has a deliberate primary purpose; short supporting context helps255 the reader proceed, while substantial digressions link to their own pages.256- The audience and their goal were identified before writing, and the first257 screen serves that goal. The first working path needs no unexplained setup258 or up-front choice among configuration alternatives, and it is safe to run259 on a developer machine as written.260- Examples teach intended idioms and identify relevant traps without turning261 a tutorial into an exhaustive list of alternatives.262- Examples are source-verified, complete at their stated scope, and show a263 checkable result; longer examples come from compiling sample or spec source.264 Explanations of what happened match the backend the reader built.265- The entry point, terminology, and next-step links fit the surrounding docs.266- A new or materially changed journey has fresh-context reader evidence, or267 explicitly reports that review as unavailable. Missing steps and guessed268 prerequisites are gaps, not reader success.269- All internal links resolve; all external links are real.270- Mermaid blocks are syntactically valid.271- The file ends with a single trailing newline.