Cratis documentation authoring
Draft one accurate Cratis documentation page in the voice and structure required
by its document type. This skill owns content. It does not decide which
repository owns a page, wire site navigation, locate an existing source page, or
perform visual QA.
Read cratis-documentation-writing for the reader journey and the
documentation rule for Platform naming and
product-claim constraints. Use those shared contracts rather than inventing
a second review procedure here. Before drafting, read and use
Explaining code, including both worked
transformations. Choose the detail in your example that will carry its
explanation; apply the multi-client section before choosing shared prose,
tabs or separate guides.
Required inputs
Before drafting, establish:
- the owning repository and destination page;
- document type: tutorial, how-to, explanation, or reference;
- target reader and the outcome they need;
- authoritative product source for every API, command, version, and capability;
- explicit scope and important exclusions.
Use repository evidence to resolve routine details. Ask only when materially
different document types, audiences, or product choices remain plausible.
Route near misses
- New-page placement or navigation is unresolved: read the owning repository's
source map, site configuration, and local documentation instructions first.
- The source of an existing page is unresolved: find its authored source before
editing; never patch a synchronized copy.
- Rendering or visual layout is requested: use the owning site's preview and
screenshot workflow, checking both light and dark presentation when relevant.
- A product/API claim lacks first-party source evidence: stop and identify the
missing authority instead of drafting the claim.
- The subject is not Cratis product or engineering documentation: do not apply
this skill.
Write to one primary reader need
Use Diátaxis to choose the page's main job. Include brief context needed to make the task work; link out instead of embedding a different page's full lesson or lookup:
| Type |
Reader need |
Shape |
| Tutorial |
Learn by completing a guided outcome |
Ordered steps with visible results |
| How-to |
Solve one concrete problem |
Prerequisites, direct procedure, necessary concepts and effects beside the step, completion check |
| Explanation |
Understand why and when |
Concepts, boundaries, trade-offs; useful diagrams or short examples, not a full procedure |
| Reference |
Look up exact information |
Exhaustive tables, fields, commands, signatures; short explanation where a default or interaction needs it |
Read site-format.md when drafting a page for the Cratis Astro Starlight site; the owning repository’s stricter format remains authoritative.
Drafting workflow
- Open where the reader's task starts. A tutorial can introduce a concrete
problem and the capability that helps; a lookup can state its contract directly.
Include context when it helps the reader act or understand.
- Organize by the reader's workflow, not by implementation namespaces or an
alphabetical API dump.
- Use active voice, present tense and American English. Address the reader
for actions; use the component or API as subject when explaining its contract.
- Develop the explanation from the concrete example, following Explaining
code. Establish what changes and why it matters, then build toward the next
action or expectation. Check ownership, host boundaries, connecting identifiers,
defaults, observable results and failure/recovery behavior as relevant. Weave
the answers into the explanation where they help; they are not a public
paragraph template. Include only components the task needs.
- Use cratis-technical-examples for code and samples: verify every API
and command against first-party source at the applicable revision, and
never translate a C# example into another client language by guess.
- Explain maturity, authorization, side effects, unsupported surfaces or a
simpler alternative when they change the reader's choice, action or expectation.
Keep an important warning before the risky action and a consequential limit
beside the behavior it qualifies.
- Show a visible result in tutorials and procedures. Use Mermaid where it
clarifies a non-trivial relationship, not as a requirement on every explanation.
- Read the resulting explanation as connected prose, using Explaining code
to repair a missing connection rather than add stock labels. Keep shared
concepts distinct from source-checked client behavior; code shape alone
proves no parity. Link the next page or workflow when the reader has a useful
next step; do not add a stock ending to a complete answer.
Correctness boundary
Never invent product APIs, customer claims, versions, support commitments,
marketplace availability, or private implementation details. Do not copy a code
sample from memory. If the source cannot prove a claim, omit it or mark the gap
for the owning maintainer.
A successful build proves rendering, not technical correctness. The owning
repository still runs its documentation, snippet, link, and product gates.
For a new or materially changed journey, use the
fresh-context reader review
owned by cratis-documentation-writing. Report unavailable independent review;
source checks and a successful build do not prove comprehension.
Output
Return or write the page content only at the already approved destination. Do
not modify navigation, generated copies, project context, credentials, package
manifests, or unrelated documentation. Report the authoritative source checked
and the verification that still remains.
1---2name: cratis-engineering-docs-authoring-23description: Use when drafting a Cratis tutorial, how-to, explanation or reference after its reader, owning page and product evidence are known. Not for locating pages, wiring navigation or visual QA.4license: LICENSE5metadata:6 source: https://skillmd.com/skills/cratis/cratis-engineering-docs-authoring-27 cratis-hint-paths: "**/Documentation/**/*.{md,mdx}"8---910# Cratis documentation authoring1112Draft one accurate Cratis documentation page in the voice and structure required13by its document type. This skill owns **content**. It does not decide which14repository owns a page, wire site navigation, locate an existing source page, or15perform visual QA.1617Read **cratis-documentation-writing** for the reader journey and the18[documentation rule](../../rules/documentation.md) for Platform naming and19product-claim constraints. Use those shared contracts rather than inventing20a second review procedure here. Before drafting, read and use21[Explaining code](references/explaining-code.md), including both worked22transformations. Choose the detail in your example that will carry its23explanation; apply the multi-client section before choosing shared prose,24tabs or separate guides.2526## Required inputs2728Before drafting, establish:2930- the owning repository and destination page;31- document type: tutorial, how-to, explanation, or reference;32- target reader and the outcome they need;33- authoritative product source for every API, command, version, and capability;34- explicit scope and important exclusions.3536Use repository evidence to resolve routine details. Ask only when materially37different document types, audiences, or product choices remain plausible.3839## Route near misses4041- New-page placement or navigation is unresolved: read the owning repository's42 source map, site configuration, and local documentation instructions first.43- The source of an existing page is unresolved: find its authored source before44 editing; never patch a synchronized copy.45- Rendering or visual layout is requested: use the owning site's preview and46 screenshot workflow, checking both light and dark presentation when relevant.47- A product/API claim lacks first-party source evidence: stop and identify the48 missing authority instead of drafting the claim.49- The subject is not Cratis product or engineering documentation: do not apply50 this skill.5152## Write to one primary reader need5354Use Diátaxis to choose the page's main job. Include brief context needed to make the task work; link out instead of embedding a different page's full lesson or lookup:5556| Type | Reader need | Shape |57| --- | --- | --- |58| Tutorial | Learn by completing a guided outcome | Ordered steps with visible results |59| How-to | Solve one concrete problem | Prerequisites, direct procedure, necessary concepts and effects beside the step, completion check |60| Explanation | Understand why and when | Concepts, boundaries, trade-offs; useful diagrams or short examples, not a full procedure |61| Reference | Look up exact information | Exhaustive tables, fields, commands, signatures; short explanation where a default or interaction needs it |6263Read [site-format.md](references/site-format.md) when drafting a page for the Cratis Astro Starlight site; the owning repository’s stricter format remains authoritative.6465## Drafting workflow66671. Open where the reader's task starts. A tutorial can introduce a concrete68 problem and the capability that helps; a lookup can state its contract directly.69 Include context when it helps the reader act or understand.702. Organize by the reader's workflow, not by implementation namespaces or an71 alphabetical API dump.723. Use active voice, present tense and American English. Address the reader73 for actions; use the component or API as subject when explaining its contract.744. Develop the explanation from the concrete example, following **Explaining75 code**. Establish what changes and why it matters, then build toward the next76 action or expectation. Check ownership, host boundaries, connecting identifiers,77 defaults, observable results and failure/recovery behavior as relevant. Weave78 the answers into the explanation where they help; they are not a public79 paragraph template. Include only components the task needs.805. Use **cratis-technical-examples** for code and samples: verify every API81 and command against first-party source at the applicable revision, and82 never translate a C# example into another client language by guess.836. Explain maturity, authorization, side effects, unsupported surfaces or a84 simpler alternative when they change the reader's choice, action or expectation.85 Keep an important warning before the risky action and a consequential limit86 beside the behavior it qualifies.877. Show a visible result in tutorials and procedures. Use Mermaid where it88 clarifies a non-trivial relationship, not as a requirement on every explanation.898. Read the resulting explanation as connected prose, using **Explaining code**90 to repair a missing connection rather than add stock labels. Keep shared91 concepts distinct from source-checked client behavior; code shape alone92 proves no parity. Link the next page or workflow when the reader has a useful93 next step; do not add a stock ending to a complete answer.9495## Correctness boundary9697Never invent product APIs, customer claims, versions, support commitments,98marketplace availability, or private implementation details. Do not copy a code99sample from memory. If the source cannot prove a claim, omit it or mark the gap100for the owning maintainer.101102A successful build proves rendering, not technical correctness. The owning103repository still runs its documentation, snippet, link, and product gates.104For a new or materially changed journey, use the105[fresh-context reader review](../cratis-documentation-writing/references/reader-review.md)106owned by **cratis-documentation-writing**. Report unavailable independent review;107source checks and a successful build do not prove comprehension.108109## Output110111Return or write the page content only at the already approved destination. Do112not modify navigation, generated copies, project context, credentials, package113manifests, or unrelated documentation. Report the authoritative source checked114and the verification that still remains.