Write project documentation§

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.

Give each page one purpose§

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

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.

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.

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:

[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. Markdown uses mermaid fences.

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

[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.

Write for the shared renderer§

A manual built by actions/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 defines the accepted syntax. Build in pull-request CI and deploy from the default branch as Documentation site describes.

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 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.

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.

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.

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.

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.

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 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.

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 and DITA topic guidance provide the content-shape principles used here.