Documentation Model

Portal content follows the Diátaxis framework (https://diataxis.fr/), applied by the documentation-writer skill. Every page has exactly one type, and its type determines its shape, tone, and what it may contain. Mixing types is the most common documentation failure — keep them separate.

The four types

Type	Orientation	Answers	Portal examples
Tutorial	Learning	“Walk me through it”	(rare here) Onboarding a new venture into the portal
How-to	Task	“How do I do X”	Update conventions, “add a repo” recipes in CLAUDE.md
Reference	Information	“What is X exactly”	Information architecture, repo registry, repo/venture digests, ADRs
Explanation	Understanding	“Why is it like this”	This page, system-of-systems architecture narrative, Glossary

Type of each portal surface

Surface	Diátaxis type	Notes
Repo digest	Reference	Factual snapshot; no opinions, no how-to steps
Venture digest	Reference (+ short Explanation intro)	Facts + a framing paragraph on the venture’s purpose
Architecture pages	Explanation (+ Reference diagrams)	Narrative why, with diagrams as reference
ADR	Reference	Immutable record of a decision and its context
Status dashboard / changelog / roadmap	Reference	Current facts, dated
Update conventions	How-to	Recipes for maintainers
Showcase (future)	Explanation / marketing	Persuasive, audience = public

Frontmatter contract

Every content page starts with YAML frontmatter. The type field MUST be one of tutorial | how-to | reference | explanation.

---
title: <human title>
type: reference          # diátaxis type
status: draft | living | accepted | superseded | archived
last_reviewed: YYYY-MM-DD
owner: <name>
---

Writing principles (from documentation-writer)

Clarity — simple, unambiguous language.
Accuracy — every fact, stack name, and dependency must be correct or explicitly marked Unknown.
User-centric — write for the audience of that page’s type.
Consistency — same terminology across pages; see the Glossary.

Placeholders & unknowns

Because much of the portal will later be machine-generated, unfinished content must be explicit and greppable:

> **TODO:** … for a maintainer action.
 for content awaiting generation.
Unknown / TBD for facts not yet established — never guess.
 …  wraps regions the orchestrator will own.
 …  wraps regions humans own (the orchestrator must not overwrite).