Docs System

Use Diataxis as the default structure, then bend it where this project needs civic and technical readers on the same path. Diataxis separates documentation into tutorials, how-to guides, reference, and explanation. That split is useful here because a nontechnical organizer and a Holochain implementer often need the same topic at different depths.

The local Diataxis skill turns this into an agent workflow for planning, drafting, and reviewing pages.

The information architecture has two layers. Public navigation should move readers from purpose, to solidarity-economy concepts, to Holochain fit. Contributor and reference pages should support the site without crowding first-reader paths.

Site structure

Section	Purpose	Primary reader
Start Here	Overview and the project thesis.	Everyone.
Concepts	Solidarity-economy mechanisms, institutional examples, and source-backed vocabulary.	Newcomers, organizers, evaluators.
Holochain Fit	What Holochain is, why it fits, and where bridges or external authority are required.	Evaluators and implementers.
Contributors	Writing, diagram, and site-quality rules.	Contributors and maintainers.
Reference	Stable inventories, research tools, local skills, and decision records.	Maintainers and reviewers.

Page rules

• Start with the reader’s problem, not with the project’s internal taxonomy.
• Name the primary reader route and Diataxis page type before drafting.
• Keep tutorials procedural. A tutorial should end with a visible result, and should wait until the project has runnable examples.
• Keep how-to guides task-focused. If the task changes, split the page; if the implementation path is not ready, leave the page unlisted.
• Keep reference pages complete enough to verify against, but do not make them narrative.
• Keep explanations honest about tradeoffs, especially privacy, governance authority, and bridges to regulated systems.
• Source load-bearing claims with inline reference-style links when possible.
• Link every named local page. If the page does not exist yet, call it a planned page instead of writing “read” or “see” language.

Quality gates

Before a page ships:

• Run Pilcrow or apply its local rules for prose shape.
• Run a source check for claims about institutions, law, accounting, protocol behavior, or software capabilities.
• Add a concrete example before the third paragraph if the page introduces an abstract concept.
• Use D2 when relationships, boundaries, or flows carry the argument better than prose.
• Link to the closest source artifact: README section, decision page, diagram source, or local skill.
• Avoid repeating the same concept in multiple places. Prefer a canonical page and links.
• Check local navigation after edits: no page should tell readers to visit another project page without linking it.