Docouture Authoring Guides

Documentation authoring guides

These guides define what to write on each page of a docouture documentation site: the purpose of every page, the sections it needs, what to say in each one, and what a good result looks like.

They complement the other docouture skills, they do not replace them:

• docouture-docs-internals / docouture-writing-docs-pages explain how the site works — Antora mechanics, nav.adoc, page patterns, AsciiDoc syntax, versioning.
• This skill explains the content — what each page must include, in which order, and to what quality bar.

It serves two audiences at once:

• Human authors who want to write or review a page and need to know what belongs in it.
• AI agents generating a first draft of the documentation from the repository code. An agent reading a page guide has everything it needs to produce a reviewable draft: section skeleton, per-section instructions, a copyable AsciiDoc starting point, and a quality checklist to self-verify.

How to use this skill

1. Plan the site structure first with the docouture-getting-started skill (reference/structure-planning.md). These guides assume that structure and never contradict it.
2. For each page you are about to write, open the guide for its section (see the index below) and jump to that page.
3. Follow the section-by-section instructions, start from the linked AsciiDoc skeleton (reference/skeletons/*.adoc), and check the result against the quality checklist before considering the draft done.
4. Once a page needs an edit later (not a first draft), docouture-documenting-changes hands back here for the same page's content contract, so an edit still matches its section's pattern instead of drifting from it.

The minimal structure

A docouture site scaffolds two Antora modules: ROOT (the home page only) and main (all content) — that is the only place where the word "module" applies; the documentation structure itself is organized in sections. Inside main, the navigation groups the pages into six ordered sections. Each page is tagged with a requirement level:

• 🔴 required — every documented repo should end up with this page.
• 🟠 recommended — include unless there is a specific reason not to.
• 🔵 conditional — include only if the repo actually has the surface it covers; skip cleanly (no stub) if it does not.
• ⚪ optional — include when it adds value, otherwise leave out.

These levels mark the minimum, not a ceiling. A product with more complex or more specific documentation needs can — and should — add more pages beyond the ones listed here: extra guides, extra reference pages, extra sections within a page. The guides define the floor every project must reach, and never forbid going further. Each section guide lists examples of these extra pages (basic installation and basic configuration in Getting started, a deployment guide per environment in Guides, a components catalog in Reference…).

The home page (ROOT's index.adoc) sits outside the six sections — it is the site's entry point, not a member of Overview. It has its own guide: reference/home.md.

General rules

These rules apply to every page. The per-page guides assume them and do not repeat them.

Routing rule: where does this content go?

Ask what the reader is trying to do at that moment:

One piece of content, one home. If a topic seems to belong in two places, write it once in the section that matches the reader's intent and cross-reference it from the other.

Guides vs Reference

The border where authors get lost most often — worth its own rule. Both sections talk about the same product surface, but they answer different questions:

• Guides are procedural: they show the reader how to accomplish a specific goal by following a set of structured steps. The reader is doing something and follows the page top to bottom, once.
• Reference is informational: it focuses on cause and effect — which actions produce which results. The reader is looking something up, lands mid-page from a search, reads one fact, and leaves.

The decision test — ask these questions about the content in doubt:

Examples:

• "Configure authentication" (pick a method, set three properties, verify it works) → guide. The exhaustive table of all auth.* properties it mentions → reference, linked from the guide.
• "Deploy to production" → guide. The complete list of CLI flags of the deploy command → reference.
• What pool-size does and its default → reference. When and why to raise it for your workload, step by step → guide.

Antipatterns:

• The tutorial-table hybrid. A reference table interrupted by "now restart the server and check the logs" — the steps belong in a guide; the table states facts.
• The exhaustive guide. A how-to that documents every flag "while we are here" becomes unfollowable; a guide makes choices for the reader and links the reference for the rest.
• Duplicated property docs. The same option explained in a guide and in the reference table drifts apart within months. Facts live in Reference; guides link them.

The rule of thumb when still in doubt: steps go to Guides, tables go to Reference — and each links the other.