Factory uses the four Diátaxis documentation types. Each authored document has one primary type in the document map. The site shows that type beside the title and groups pages by reader need.
| Type | Reader need | What belongs here |
|---|---|---|
| Tutorial | Learn by doing | A complete, repeatable exercise with an expected result |
| How-to guide | Finish a task | Prerequisites, steps and confirmation of success |
| Reference | Look up a fact | Exact contracts, limits, definitions and evidence |
| Explanation | Understand a decision | Reasons, alternatives and relationships |
One owner per topic
| Topic | Authoritative document | Other pages should |
|---|---|---|
| Current module acceptance and review evidence | Build review | Link to the relevant evidence; retain only the local scope needed to understand the page |
| Module APIs, bounds and composition limits | Module references | Explain the purpose and link to the contract |
| Local Portfolio commissioning data | Portfolio record | Link to the historical record |
| Canonical domain definitions and intended contracts | Design | Use the same terms; link instead of restating a glossary |
| Why the delivery stages exist | Lifecycle overview | Link to the explanation |
| Proposed architecture diagrams | Architecture | Link to the relevant diagram |
| Proposed discovery and post-development behaviour | Lifecycle design | Label it proposed and link |
| Customer outcomes and completion criteria | Implementation plan | Link to the specific outcome |
| Contribution authority and review protocol | Working instructions | Link to the rules rather than copy them |
| Changing operational status | Handover and its canonical Notion link | Update in place; keep chronology in immutable evidence |
| Brand voice and visual rules | Brand guide, design language | Use the shared tokens and link to the rule |
Writing and maintenance
Choose the reader's need before writing. A module explanation should answer why the part exists and how it relates to its neighbours. Its reference owns the detailed API. A task page should end with a way to confirm the task succeeded.
Keep a brief scope statement where a reader might mistake a proposal for a working product. Keep dates, review rounds and historical test counts in the evidence ledger. Do not paste the project status into every introduction.
Use plain British English, active verbs and short sentences. Preserve technical names and honest limits. Marketing describes the intended customer benefit; status pages hold implementation detail. An aspiration must not imply that a planned capability is available today.
Coverage
The document map includes public docs, agent references, root contributor documents and internal intent records. Maintainer documents are classified but are not added to the public navigation. JSON evidence, test fixtures, generated pages and image assets are not authored prose documents. Adding a page without a classification fails the docs build.
Existing URLs and heading anchors remain valid when content moves. Leave a focused pointer at the old location and put the full explanation in its authoritative page.