> Documentation version: 3. [HTML page](documentation.html)

<a id="write-project-documentation"></a>

# Write project documentation

Use this guide when creating or reviewing documentation for a Roc package,
platform, application or shared tool. Organize it around the reader’s task and
keep claims tied to evidence.

<a id="risk-documentation-claims"></a>

## Risks and controls for documentation claims

A documented command can drift from its interface, or a status claim can imply
stronger evidence than its check provides. Reuse checked examples, build every
published format, verify links and rendered content, and review operational
evidence for process claims. Keep risks beside the task so qualifications
survive copying an example. Rendering checks establish publication integrity;
they do not validate every technical assertion or prove that an operator
followed the process.

<a id="give-each-page-one-purpose"></a>

## Give each page one purpose

Choose the reader’s need before writing. The Diátaxis forms distinguish four
useful page shapes:

| Form | Reader need | Shape |
| --- | --- | --- |
| Tutorial | Learn through a first success | A safe, linear path with a visible result |
| How-to guide | Complete a task | Steps that assume relevant knowledge |
| Reference | Look up exact facts | Descriptions organized like the interface |
| Explanation | Understand a design or tradeoff | Connected reasoning that answers why |

Link between these forms. Split a page when its sections serve different
readers or outcomes; an option catalogue should not interrupt a first-use guide.

<a id="define-the-page-before-drafting"></a>

## Define the page before drafting

Identify the reader, their assumed knowledge, the question the page answers and
the result they should reach. Lead with that result, put prerequisites beside
the first step, and use copyable examples with observable output.

Introduce unfamiliar concepts through the problem they solve before presenting
an API. Explain what the reader supplies, what the tool returns and when it is
appropriate. Keep implementation architecture and contributor concerns in their
own chapters. Have someone unfamiliar with the feature review the first-use
path for undefined terms and unanswered questions.

<a id="show-structure-and-behavior"></a>

## Show structure and behavior

Use a Mermaid diagram when relationships, state changes, trust boundaries or a
multi-stage process are harder to explain in prose. Make one point per diagram
and place it beside the explanation. Prefer stable concepts to incidental
implementation details.

In AsciiDoc, keep the Mermaid source in the document. The renderer produces SVG
for the website and vector figures for PDF:

``` asciidoc
[mermaid]
....
flowchart LR
    Source[Roc target] --> Build[roc build --fuzz]
    Build --> Runner[Self-contained runner]
    Runner --> Corpus[Coverage corpus]
    Runner --> Failure[Reproducing failure]
....
```

Give diagrams descriptive captions and labels that work in grayscale. Use the
[supported Mermaid subsets and limits](roc-docs.md#images-and-diagrams).
Markdown uses ` mermaid ` fences.

Use language-labelled source blocks for commands, configuration, code and output.
Keep examples short enough to scan:

``` asciidoc
[source,roc]
----
target = Fuzz.target({ name: "parser", test, show })
----
```

Prefer examples that CI exercises. Label intentionally incomplete snippets,
separate commands from output, and explain errors without relying on colour.

<a id="write-for-the-shared-renderer"></a>

## Write for the shared renderer

A manual built by [` actions/build-docs `](actions.md#build-docs) has one
entrypoint and one file per chapter. The renderer produces a combined website,
chapter pages, static Markdown and a PDF.

- Keep chapters directly under ` docs/ `; subdirectories are copied unrendered.


- Make ` index.adoc ` a ` :doctype: book ` with one
  ` include::<chapter>.adoc[leveloffset=+1] ` per chapter.

- Open each chapter with a single ` = Title ` that names its task or subject.


- Let IDs follow headings where possible. By default, ` == Host bindings `
  becomes ` host-bindings `. Use an explicit ` [#id] ` for a public target that
  must survive rewording.

- Link chapters with ` xref:chapter.adoc#section-id[link text] `. Include the
  section ID so the link works in the book, chapter page and PDF. Keep
  ` <<section-id>> ` references to ` index.adoc `, where both ends are present.

- Attributes in ` index.adoc ` do not reach standalone chapter pages. Do not rely
  on a book-only attribute inside a chapter.

- Give tables explicit widths, such as ` [cols="1,2",options="header"] `.


- Use ` {docs-version} ` for the version label supplied by the workflow.


- Treat renderer warnings, missing includes and malformed blocks as failures.


- Ignore ` .docs-out/ ` in ` .gitignore `.


The [source reference](roc-docs.md#source-formats-and-links) defines the
accepted syntax. Build in pull-request CI and deploy from the default branch as
[Documentation site](optional-workflows.md#documentation-site) describes.

<a id="experimental-native-docs-contract"></a>

## Publication contract

The renderer owns the theme, navigation, highlighting and validation policy.
Repositories supply content, metadata, entrypoints and prepared assets through
the CLI or action inputs. The source subset and preparation inventory remain
experimental; use the [utility reference](roc-docs.md#build-documentation-with-roc-docs)
for their current boundaries.

Build and execute the renderer in read-only jobs. Pin its release and reviewed
binary digest, verify downloaded and cached bytes before execution, and pin
shared actions to full SHAs. ` actions/build-docs ` consumes a supplied executable;
its provisioning and admission belong to the caller.

Sources and assets are inert data. Includes stay local, the renderer fetches no
remote images, and Mermaid parsing/layout runs under resource limits. Generated
SVG contains escaped text, reviewed embedded fonts and renderer-owned geometry.
Output is staged so a parse, resource or collision failure preserves the
previous publication. Tests exercise these refusals without external renderers
on ` PATH `; maintainers still review diagram meaning and page fitting.

Keep API generation, release-snippet generation and interactive example builds
as explicit tasks. Only the optional API stage requires a caller-supplied
compiler; ordinary rendering needs no compiler or external rendering runtime.

<a id="one-manual-several-audiences"></a>

## One manual, several audiences

Order the manual from first use through everyday tasks and reference to
contributing and maintenance. Introduce each audience’s starting point in the
entrypoint. Keep setup, architecture and maintainer procedures in their own
chapters, with links where another reader needs them.

<a id="keep-documentation-current"></a>

## Keep documentation current

Every paragraph must help a current user or contributor complete a task, look up
a contract or understand a relevant design choice. Remove a paragraph if deleting
it would leave those readers equally able to use and maintain the project.

Delete superseded instructions and implementation chronology; Git history keeps
them available. Put investigation notes and pending work in issues, and
release-specific changes in the published release. Keep compatibility guidance
only while a supported reader needs it. Preserve public anchors without adding
prose about their age or retention.

Revise the owning section when behavior changes instead of appending a status
note. Link to one authoritative explanation rather than repeating it across
chapters. Apply the same review to READMEs and contributor guides.

<a id="keep-the-readme-short"></a>

## Keep the README short

The README is the front door. State the problem and audience, show a small
example or screenshot, and link to the manual, releases and minimal setup.
Move task instructions into the relevant manual chapter rather than growing a
second manual in the README.

` CONTRIBUTING.md ` points to the contributing chapter. ` SECURITY.md ` gives the
private reporting channel. Keep license and third-party notices in their
required locations and link to them.

<a id="cover-the-public-project-experience"></a>

## Cover the public project experience

Check the connected path a user follows, including:

- purpose, supported scope and obtaining a verified release;


- a first working example with expected output;


- normal tasks and recovery from common failures;


- public commands, inputs, outputs, configuration, formats and APIs;


- supported platforms and practical limitations;


- feedback, bug reports, contribution and private security reporting; and


- release changes, licenses and applicable third-party notices.


Keep task and reference guidance in the manual. Link to release records and
root notices instead of reproducing them.

<a id="publish-static-markdown"></a>

## Publish static Markdown for retrieval

The build publishes static Markdown and an ` llms.txt ` chapter index by default.
Each HTML chapter links to its Markdown equivalent. These are ordinary files
served with the same Pages artifact; use ` --markdown false ` or the action input
` markdown: "false" ` to omit them. The
[utility reference](roc-docs.md#build-a-manual) describes routing and options.

Generate reader formats together so an export cannot silently lag behind the
website. Markdown uses the admitted HTML-backend tree, preserves canonical
anchors and source content, and rewrites chapter links. Unsupported content or
output collisions fail publication. Verify code bytes, headings, tables,
images, chapter coverage and discovery links against the source inventory.
Markdown does not preserve HTML styling or PDF pagination; discovery metadata
does not establish the accuracy of an agent’s answer.

<a id="review-each-change"></a>

## Review each change

Before merging documentation:

- verify links, commands, examples and expected results;


- build every published format, including optional API pages;


- inspect typography, highlighted code, diagrams and tables in HTML and PDF;


- check narrow-screen navigation, light/dark modes and PDF pagination;


- place limitations and destructive steps before the action they qualify; and


- remove superseded material and paragraphs without a current reader purpose.


The [Diátaxis framework](https://diataxis.fr/) and
[DITA topic guidance](https://docs.oasis-open.org/dita/v1.0/archspec/topicover.html)
provide the content-shape principles used here.