Use this guide when creating or reviewing documentation for a Roc package, platform, application, or shared tool. It separates the reader’s needs from the project evidence that maintainers must preserve.

Give each page one purpose

Choose the page’s dominant purpose before writing it. The four Diátaxis forms provide a useful test:

Form Reader need Shape

Tutorial

Learn by completing a guided first experience

A safe, linear path with a visible result

How-to guide

Accomplish a real task

Goal-oriented steps that assume relevant knowledge

Reference

Look up exact facts

Complete, neutral descriptions organized like the interface

Explanation

Understand context, design, or tradeoffs

Connected reasoning that answers why

A page can link to another form, but should not interrupt a tutorial with an exhaustive option catalogue or turn reference material into a narrated lesson. Use one topic for one subject or reader question. Split a page when its sections serve different audiences or outcomes.

The manual’s reading order may still follow a natural journey: context, first success, goal-oriented guides, reference, contributor material, then appendices. The four forms are an editing discipline rather than required top-level folders.

Define the page before drafting

Record these answers in the issue, pull request, or draft notes:

  • Who is the intended reader?

  • What do they already know and have installed?

  • What question will this page answer?

  • Which documentation form fits that question?

  • What should the reader be able to do or understand afterward?

  • Which commands, interfaces, versions, and platforms constrain the answer?

Lead with the outcome. Keep prerequisites close to the first step. Use complete, copyable examples and explain the observable result. Link to detailed reference or background when it would distract from the page’s purpose.

Start from the reader’s knowledge

Name the primary audience and assume only the knowledge that audience normally has. A package user may understand Roc while knowing nothing about the native engine, protocol, algorithm, or build system behind the package. Introduce a concept in ordinary language before using its specialist name.

For an unfamiliar tool, answer these questions before presenting its API:

  • What problem does this solve in the reader’s application?

  • What must the reader provide?

  • What does the tool provide in return?

  • How does it differ from the approach the reader probably uses today?

  • What does a first successful result look like?

  • When is the tool a good fit, and when should the reader choose something else?

Use progressive disclosure. Keep implementation names, escape hatches, internal architecture, and contributor concerns in explicitly advanced or internal material until a user task requires them. Do not use the introduction as a feature inventory.

Before publication, ask a reviewer who did not design the feature to read from the primary audience’s perspective. Have them list unanswered questions, undefined terms, assumed experience, and places where they could copy commands without understanding the purpose. Resolve adoption and first-use gaps before polishing expert reference material.

Show structure and behavior

Use a Mermaid diagram when relationships, state changes, trust boundaries, data flow, or a multi-stage process would take several paragraphs to reconstruct. A diagram should make one point and sit beside the prose that explains its meaning. Prefer stable concepts over incidental implementation details so it remains useful as the code changes.

In AsciiDoc sources built by actions/build-docs, embed Mermaid source so the same diagram is rendered into the HTML site and 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 every diagram a descriptive title or nearby textual explanation. Do not put information only in color, and make labels meaningful when printed in grayscale. Keep the Mermaid source readable because it is also the maintainable form of the diagram.

Use syntax-highlighted source blocks for commands, configuration, source code, schemas, reports, and output. Name the language explicitly and keep examples focused enough to scan:

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

Prefer examples that CI compiles or exercises. When a snippet is intentionally incomplete, say what was omitted. Separate commands from their output, label both, and never rely on highlighting alone to communicate an error or required change.

Write for the shared renderer

A manual built by actions/build-docs is a book with one entrypoint and one file per chapter. The renderer produces the whole book as index.html, a separate HTML page for every chapter, and a PDF. A few rules keep all three outputs correct.

  • Keep every chapter directly under docs/. Only top-level .adoc files are rendered as pages; a subdirectory is copied to the site unrendered.

  • Keep release notes in docs/releases/<version>.adoc, and pull them into the manual from a top-level releases.adoc chapter with one include::releases/<version>.adoc[leveloffset=+1] line for each, newest first. They are then rendered in the book, on their own page and in the PDF.

  • Make index.adoc a :doctype: book that pulls in each chapter with include::<chapter>.adoc[leveloffset=+1].

  • Open every chapter with a single = Title. Prefer a title that names what the reader will do.

  • Let section IDs be generated from headings. The renderer writes them in lowercase with hyphens, so == Host bindings becomes host-bindings. Give an explicit [#id] only where a heading starts with markup or is likely to be reworded.

  • Link between chapters with xref:chapter.adoc#section-id[link text], always with a section ID and link text. That form resolves in the book, in the chapter page and in the PDF. A link to a chapter with no section ID is dead in the book, and <<section-id>> resolves only where both ends are in the same output, so keep it to index.adoc.

  • Attributes set in index.adoc do not reach a chapter rendered as its own page. Do not rely on a custom attribute inside a chapter.

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

  • Use {docs-version} for the version label; the workflow supplies it.

  • Treat every renderer warning as an error. The build fails on a missing include or a malformed block.

  • Ignore the output directory, .docs-out, in .gitignore.

Build the manual in a pull request, and deploy it from the default branch, as described in Documentation site.

One manual, several audiences

A project has more than one kind of reader: someone deciding whether to use the package, someone using it for the first time, an experienced user looking up a detail, a contributor, a maintainer cutting a release, a person verifying a download. Their needs differ, and they should all be served by one unified document, the manual, and not by notes scattered across the repository.

  • Put contributor notes, maintainer procedures, architecture and release history in the manual, as chapters beside the user documentation. A reader then has one place to look and one table of contents to scan, and a single build keeps every part current.

  • Decide what each section is for before writing it. Name the reader it serves and what that reader should be able to do afterwards. A section that cannot answer both is not ready to be written.

  • Introduce information gradually. Order the manual from the reader who knows least to the reader who knows most: what the project is, a first success, everyday tasks, reference, then contributing and maintenance. No chapter should require something a later chapter explains.

  • Keep audiences apart. A getting-started chapter does not stop to explain the release process, and a maintainer chapter does not re-teach the basics. Link across instead.

  • Tell each reader where to start. Open the manual with a short guide that sends each kind of reader to their chapter.

Keep the README short

A README is the front door, and it faces users. It answers three questions and then hands over to the manual: what is this, what does it look like, and where do I go next.

  • One or two sentences saying what the project is and who it is for.

  • A prominent link to the documentation site, and to the latest release.

  • A grid of screenshots or short examples. A picture of the output, or a few lines of code beside what they produce, tells a visitor more in five seconds than a page of prose. Choose a handful that show the range of the project.

  • A minimal install or usage snippet, when one fits in a few lines.

A README must never become a dumping ground. Build instructions, contributor setup, design notes, troubleshooting and release procedure all belong in the manual. When something seems to need adding to the README, add it to the manual and link to it. A README that has grown past a screen or two has usually started doing the manual’s job, and the two then drift apart.

The same holds for the other root files. CONTRIBUTING.md is a short pointer to the contributing chapter. SECURITY.md states how to report a vulnerability. Neither carries guidance that is not also in the manual.

Cover the public project experience

Review the documentation as a connected entry path, not only as individual pages. A user should be able to find:

  • a concise statement of the problem the project solves and its supported scope;

  • how to obtain a released version and verify any required toolchain;

  • a minimal working example with expected output or behavior;

  • task-oriented guidance for normal operation and common failures;

  • reference for every public input, output, command, option, configuration value, file format, and API;

  • compatibility, support, and known limitation information;

  • where to report bugs, request enhancements, discuss changes, and privately report vulnerabilities;

  • how to contribute, including the change process, standards, tests, and checks;

  • human-readable release notes and upgrade impact; and

  • license, third-party notices, provenance, and acknowledgments where applicable.

All of these live in the manual, as one document. The files that hosting services and tools expect at the repository root, such as README.md, CONTRIBUTING.md, SECURITY.md and LICENSE, stay there and stay short; see Keep the README short.

Keep claims testable

Documentation is evidence of a declared process, not proof that the process is followed. For every operational claim, identify how it is checked:

Claim Useful evidence

The documented build works

A clean CI job runs the same command

Published examples work

The release tests its examples archive before upload, and a nightly run tests the published archive unchanged

The test suite is the contribution gate

Contributor instructions and required CI run the stated command

The external interface is documented

An API or schema audit fails when public entries are missing

Releases are reproducible and identifiable

Immutable tags, artifact digests, provenance, and release notes

Vulnerability reports receive timely responses

A working private channel and periodically reviewed response history

Prefer generated reference material only when generation is complete, readable, and checked. Handwritten explanations and examples still need review when the interface changes.

Review each change

Before merging documentation:

  • verify links, commands, examples, and expected results;

  • build every published format, including HTML, PDF, and generated API pages;

  • inspect Mermaid diagrams and highlighted code in both HTML and PDF output;

  • check headings and links without relying on generated numbering;

  • confirm the navigation names describe reader goals or subjects;

  • check that warnings, limitations, and destructive steps appear before the action they qualify;

  • review accessibility of diagrams, tables, link text, and color use;

  • remove stale version claims and resolved temporary limitations; and

  • update the project evidence inventory when a URL or process changes.

Project-practice evidence supplies the companion checklist for repository and operational evidence. The Diátaxis framework and DITA topic guidance are the sources for the content-shape principles used here.