-
Notifications
You must be signed in to change notification settings - Fork 4.4k
14.2 Documentation Standards
Source: #5576 · Part of the Maturity Framework. This page mirrors the RFC body; discussion lives on the issue.
A note to the team before you read this.
Documentation is not what you write after the code is done. It is a product surface in its own right — the interface between the project and every person who will ever contribute to it, use it, or build on it. A codebase with no documentation forces every new person to rediscover everything from scratch. A codebase with bad documentation is often worse, because it gives people false confidence. This RFC proposes treating documentation with the same intentionality we are applying to the architecture: Vision first, then structure, then content.
- The Documentation Philosophy
- Honest Assessment: Where We Are Today
- A Classification Framework: EA Artifacts on a Page
- The i18n Problem
- The Repo / Wiki Split
- ADR Standards
- AGENTS.md as the AI Development Layer
- The Target Structure
- The Replacement docs-contract
- Standards We Should Adopt
- Phased Roadmap
- Discussion Questions for the Team
Documentation problems almost always come from skipping a question that should have been asked before writing the first sentence: what kind of document is this, and who is it for?
Without an answer to that question, documentation accumulates as a pile of pages that are all slightly different shapes of the same vague category: "stuff about the project." Setup guides live next to architecture decisions. User-facing how-tos sit alongside internal coding standards. Thirty language translations of the README compete for space with the single security policy document. Nobody can find anything, everything goes stale at a different rate, and every PR that touches documentation becomes a negotiation about which pages need updating.
The fix is not to write more documentation. The fix is to decide, before writing anything, what type of artifact you are creating. Type determines format, audience, location, lifecycle, and who is responsible for keeping it current. Once type is established, the rest follows naturally.
This RFC adopts the EA Artifacts on a Page framework by Svyatoslav Kotusev (https://eaonapage.com) as the classification lens for all ZeroClaw documentation. The framework is evidence-based, deliberately non-prescriptive, and maps directly onto the kinds of documents an open source infrastructure project actually needs.
The core principle, borrowed from the broader development philosophy this team is adopting:
Documents, like code, should trace a line upward through Vision → Architecture → Design → Implementation. If you cannot name the artifact type and its audience before writing, you are not ready to write.
The most immediately measurable problem in the current documentation is the localization system:
| Metric | Value |
|---|---|
| Non-English README files at repo root | 31 |
Files in docs/i18n/
|
169 |
Disk space consumed by docs/i18n/
|
2.2 MB |
Actively "supported" locales per docs-contract.md
|
6 (en, zh-CN, ja, ru, fr, vi) |
| Locales with README files at root | 31 |
The i18n system creates a contributor tax on every documentation PR. The current docs-contract.md contains this requirement:
If a change touches docs IA, runtime-contract references, or user-facing wording in shared docs, perform i18n follow-through for supported locales in the same PR.
This means a contributor fixing a typo in a setup guide must update up to six language versions of that document, or the PR fails review. This is a significant barrier to contribution, particularly for the students and early-career engineers who make up most of this project's contributor base.
The current docs/ hierarchy mixes three fundamentally different document types at the same level:
- Code-adjacent documents that must version with the codebase (ADRs, API specs, security policy, contribution process)
- User-facing operational documents that should update independently of code releases (setup guides, troubleshooting, deployment how-tos)
- Community documents that should be community-maintained and need no formal review process (translations, FAQ, community guides)
All three live in docs/ with no structural distinction between them. The result is a flat pile with a hand-maintained SUMMARY.md that someone has to update every time anything changes.
The project has exactly one Architecture Decision Record: ADR-004-tool-shared-state-ownership.md. It is excellent — well-structured, code-referenced, specific. But the project has made at least five or six architectural decisions of equal or greater consequence that have never been recorded:
- The choice of Rust over TypeScript
- The trait-driven extensibility model
- The WASM plugin system design
- The choice of SQLite and Markdown as the two memory backends
- The security model (pairing codes, autonomy levels, sandbox layers)
Without these records, every new contributor must rediscover the reasoning through code archaeology. Every AI coding assistant that reads the codebase gets the what but not the why. This is one of the most expensive forms of undocumented technical debt.
The docs-contract.md concept — treating documentation as a governed product surface — is the right instinct. It just needs the right rules. The AGENTS.md at the root is excellent and sets the right precedent for AI-assisted development. ADR-004 proves the team can write high-quality architectural records.
The EA Artifacts on a Page framework defines five families of architecture artifacts. Every document in the ZeroClaw repository should belong to one of these families, and that family determines everything about where it lives, how it is formatted, and when it becomes stale.
| EA Artifact Family | The Question It Answers | Examples in ZeroClaw | Location |
|---|---|---|---|
| Considerations | What principles and standards guide our decisions? |
AGENTS.md files, coding standards, security policy, this doc |
docs/contributing/ or per-crate |
| Landscapes | What does the system look like right now? | Component maps, crate topology, dependency diagrams | docs/architecture/ |
| Outlines | Where are we going? | RFCs and roadmap proposals | docs/proposals/ |
| Designs | How exactly are we doing this specific thing? | ADRs, OpenAPI specs, WIT interface files | docs/architecture/decisions/ |
| Standards | What are the specific rules for how we build? | PR workflow, testing standards, release process | docs/contributing/ |
What is notably absent from this table: user guides, setup instructions, channel-specific how-tos, troubleshooting, FAQ. These are operational content, not EA artifacts. They do not version with the code. They belong on the GitHub Wiki.
Before writing any document, ask and answer these two questions:
- What artifact family is this? If you cannot answer this, you are not ready to write.
- Does it need to version with the code? If yes, it goes in the repository. If no, it goes on the Wiki.
A useful test for the second question: would this document become wrong or misleading if someone read it against a different version of the codebase? If yes, it lives in the repo, versioned with the code. If no, it lives on the Wiki.
The case for removing all non-English content from the repository rests on four pillars:
1. The audience has on-demand translation. ZeroClaw's primary users are people running an AI assistant. Every such person has access to instant, high-quality machine translation — either through the agent they are running, through their browser, or through any of dozens of free translation services. The practical benefit of shipping translations in the repository is marginal.
2. The translations are almost certainly stale. Machine-translated content was likely generated once and has not been kept synchronised with the English source. Stale documentation is worse than no documentation for AI-assisted development, because language models will confidently derive incorrect conclusions from outdated information.
3. The contributor tax is real and measurable. The docs-contract.md parity requirement means every documentation PR must touch up to six language versions. This makes documentation contributions expensive and discourages exactly the kind of small, incremental improvements (fixing a typo, clarifying a step, updating a stale reference) that keep documentation healthy.
4. Localization is community work, not core project work. The communities best positioned to maintain Japanese documentation are Japanese-speaking contributors. Putting localized content in the main repository with a parity requirement places the burden on the core maintainers instead of the communities who benefit. The GitHub Wiki inverts this correctly: community members can edit and maintain their language's pages without opening PRs.
One thing worth preserving: the structure of the i18n approach. The idea of making ZeroClaw accessible in multiple languages is right. Only the location and ownership model is wrong.
-
Remove all
README.*.mdfiles from the repository root, exceptREADME.md -
Remove
docs/i18n/entirely -
Remove all non-English hub files from
docs/(e.g.docs/README.zh-CN.md) -
Add a
Languagessection to the mainREADME.md:Translations: Community-maintained translations are available in the GitHub Wiki. To contribute a translation or improve an existing one, edit the Wiki directly. All languages are welcome.
-
Create a
Translationspage on the GitHub Wiki with a table of available languages, their completeness, and the contributors maintaining them -
Optionally: add a
zeroclaw docs --translateCLI feature that uses the configured LLM provider to translate any doc page on demand — a natural fit for a product whose entire purpose is AI assistance
Remove the i18n follow-through requirement from docs-contract.md. Replace it with: Documentation PRs are reviewed in English only. Translations are community-maintained on the Wiki and are not subject to PR review.
A document lives in the repository if it would become wrong when the code changes. It lives on the Wiki if it would not.
This is not a fuzzy rule. Apply it literally.
An ADR records why a specific architectural decision was made at a specific point in time. If the code changes, the ADR still accurately describes what was decided and when. The code may have evolved away from it, but the record remains accurate. → Repository.
A setup guide for configuring the Telegram channel describes steps a user takes against the current version of the software. If the configuration format changes, the guide becomes wrong. → This sounds like it should be in the repo — but it shouldn't. Setup guides should update on their own timeline, not be coupled to code commits. The right model is: the API reference (which maps directly to configuration structs) lives in the repo, and the setup guide that walks a user through using that API lives on the Wiki, updated by anyone when the steps change.
Stays in the repository (docs/):
| Current location | Artifact family | Notes |
|---|---|---|
docs/architecture/ |
Designs | ADRs, component diagrams |
docs/proposals/ |
Outlines | RFCs, roadmap documents |
docs/contributing/ |
Considerations + Standards | PR workflow, testing, coding standards |
docs/security/ |
Considerations + Designs | Security policy, sandboxing design, audit logging |
docs/hardware/ |
Designs | Peripheral design docs, datasheets |
docs/reference/api/ |
Designs | Config reference, providers reference — generated from or tightly coupled to code |
docs/reference/cli/ |
Designs | Commands reference |
Moves to the GitHub Wiki:
| Current location | Reason for moving |
|---|---|
docs/setup-guides/ |
User-facing how-tos that change independently of code |
docs/ops/operations-runbook.md |
Operational, user-maintained |
docs/ops/troubleshooting.md |
Operational, changes frequently |
docs/ops/network-deployment.md |
Operational, deployment-specific |
docs/setup-guides/mattermost-setup.md (and similar per-channel guides) |
User-facing, change with upstream platform APIs |
Deleted (i18n removal):
| Item | Size impact |
|---|---|
docs/i18n/ (169 files) |
−2.2 MB from repo |
31 × README.*.md at root |
−significant root clutter |
Non-English hub files in docs/
|
−31 files |
| i18n coverage map, i18n index | −2 files |
Home
│
├── Getting Started
│ ├── Installation
│ ├── Quick Start (TL;DR)
│ ├── Migrating from OpenClaw
│ └── Onboarding Walkthrough
│
├── Configuration
│ ├── Providers
│ ├── Channels
│ ├── Memory
│ ├── Security & Pairing
│ └── Tunnels
│
├── Channels
│ ├── Telegram
│ ├── Discord
│ ├── Slack
│ ├── WhatsApp
│ └── ... (one page per channel)
│
├── Operations
│ ├── Troubleshooting
│ ├── Deployment
│ ├── Network Setup
│ └── Performance Tuning
│
├── Hardware
│ ├── Getting Started with Peripherals
│ ├── ESP32 Setup
│ ├── STM32 Nucleo Setup
│ └── Arduino Setup
│
└── Community
├── FAQ
├── Translations
└── How to Contribute
All Architecture Decision Records use the Nygard format, extended with YAML frontmatter for machine readability. ADR-004 is the existing model — this section formalizes it.
Every ADR has three sections and five frontmatter fields:
---
id: ADR-NNN
title: Short imperative sentence describing the decision
date: YYYY-MM-DD
status: proposed | accepted | deprecated | superseded-by-ADR-NNN
relates-to:
- ADR-XXX (optional, list of related decisions)
- crates/zeroclaw-api (optional, affected code paths)
---
# ADR-NNN: Title
## Context
What is the situation, constraint, or problem that required a decision?
What forces were at play? What options were considered?
## Decision
What was decided? State it in the active voice.
"We will..." not "It was decided that..."
## Consequences
What are the results of this decision?
List both positive consequences and negative ones — every decision has tradeoffs.
Note any follow-up decisions or actions this creates.
## References
Links to the relevant code files, issues, and external resources.
-
ADRs are immutable once accepted. If a decision changes, the old ADR is marked
superseded-by-ADR-NNNand a new ADR is written describing the new decision and why it superseded the old one. - ADRs are numbered sequentially and never renumbered. Gaps in the sequence are acceptable (a proposed ADR that was rejected can be withdrawn, leaving a gap).
-
ADRs live in
docs/architecture/decisions/. They are namedADR-NNN-short-slug.md. - Significant architectural changes require an ADR. "Significant" means: a decision that would be surprising to a new contributor, a decision that constrains future choices, or a decision that involves a non-obvious tradeoff.
The following key decisions should be documented retroactively. They represent the foundational reasoning a new contributor or AI tool needs to understand the codebase:
| Proposed ADR | Decision to record |
|---|---|
| ADR-001 | Rust as the implementation language (replacing TypeScript/OpenClaw) |
| ADR-002 | Trait-driven extensibility as the primary architectural pattern |
| ADR-003 | WASM + Extism as the plugin execution model |
| ADR-004 | Tool shared state ownership contract (already exists) |
| ADR-005 | SQLite + Markdown as the two memory backends |
| ADR-006 | CLI as the only built-in channel; all others as plugins |
| ADR-007 | Gateway extraction as a separate optional binary |
Retroactive ADRs should be marked with a note:
This is a retroactive record of a decision made prior to the formal ADR process. The date reflects when the decision was made, not when this record was written.
When an AI coding assistant reads a repository, it sees the code as it is now. It does not see the choices that were rejected, the tradeoffs that were weighed, or the reasons a particular structure was chosen over alternatives. Without ADRs, the AI will suggest changes that violate architectural constraints it has no way of knowing about. With ADRs, the reasoning is explicit and machine-readable. The frontmatter makes ADRs queryable: an AI tool can find all ADRs related to zeroclaw-api and load them as context before editing that crate.
The root AGENTS.md is the project's strongest existing contribution to AI-assisted development. It tells AI coding assistants the commands to run, the architecture to respect, the risk tiers to apply, and the anti-patterns to avoid. It works because it is specific, opinionated, and short.
As the workspace decomposes into crates (per the microkernel architecture RFC), each crate should have its own AGENTS.md. This is the mechanism by which architectural boundaries become enforceable at the AI-assistance layer — not just at compile time through crate dependencies, but at the reasoning layer before any code is written.
Keep them short. An AGENTS.md that is longer than 60 lines will not be read. Each file answers five questions:
# <crate-name>
## What this crate is
One or two sentences. What problem does this crate solve?
## What this crate is allowed to depend on
List the crates this crate may import. Be explicit.
If a dependency is not listed here, do not add it without an ADR.
## Extension points
Where can new implementations be added? What trait do they implement?
Link to the relevant traits.
## What does NOT belong here
Explicit anti-patterns. What would be a mistake to add to this crate?
## Related ADRs
- ADR-NNN: Short titleFor crates/zeroclaw-api (once extracted):
# zeroclaw-api
## What this crate is
Trait definitions and shared data types for the ZeroClaw plugin and kernel
interfaces. This is the contract layer. Everything else depends on it.
## What this crate is allowed to depend on
- serde, serde_json (serialization)
- async-trait (async trait support)
- anyhow (error types)
- tokio (async runtime types, minimal)
Nothing else. No HTTP clients. No database drivers. No external services.
## Extension points
All traits in this crate are extension points:
- `Provider` (src/providers/traits.rs) — LLM provider implementations
- `Channel` (src/channels/traits.rs) — messaging platform integrations
- `Tool` (src/tools/traits.rs) — agent tool implementations
- `Memory` (src/memory/traits.rs) — persistence backends
- `Observer` (src/observability/traits.rs) — observability backends
- `RuntimeAdapter` (src/runtime/traits.rs) — execution environments
- `Peripheral` (src/peripherals/traits.rs) — hardware integrations
## What does NOT belong here
- Any concrete implementation of any trait
- Any dependency on a specific messaging platform, LLM provider, or database
- Any network I/O or filesystem access
- Any binary or executable target
## Related ADRs
- ADR-002: Trait-driven extensibilityFor crates/zeroclaw-kernel (once extracted):
# zeroclaw-kernel
## What this crate is
The orchestration engine. Runs the agent loop, manages the service registry,
exposes the local IPC API. The kernel knows nothing about specific channels,
providers, or tools — only their abstract interfaces.
## What this crate is allowed to depend on
- zeroclaw-api (traits only)
- zeroclaw-tool-call-parser (parsing, no agent state)
- Standard async/runtime crates (tokio, anyhow, tracing)
- Config and storage crates (toml, serde, rusqlite for core memory)
NOT: any specific channel, provider, or tool implementation crate.
## Extension points
- `Registry::register_channel()` — add a channel at startup
- `Registry::register_tool()` — add a tool at startup
- `Registry::set_provider()` — set the active provider at startup
Implementations are registered by the binary crate, not by the kernel.
## What does NOT belong here
- Any import of TelegramChannel, DiscordChannel, or any named channel
- Any import of AnthropicProvider, OpenAIProvider, or any named provider
- Any tool implementation beyond the 10-12 designated core tools
- The gateway HTTP server or any web serving code
## Related ADRs
- ADR-002: Trait-driven extensibility
- ADR-006: CLI as the only built-in channel
- ADR-007: Gateway extractionThe root AGENTS.md sets project-wide policy. Crate-level AGENTS.md files narrow that policy for their specific scope. When an AI tool reads a file in crates/zeroclaw-api/, it should read both the root AGENTS.md (project policy) and crates/zeroclaw-api/AGENTS.md (crate policy). Crate policy is more specific and takes precedence where they conflict.
After the changes proposed in this RFC, the repository's documentation layout becomes:
docs/
│
├── README.md ← Hub: links to wiki for user guides,
│ to proposals/ for roadmap, to
│ architecture/ for decisions
├── SUMMARY.md ← Canonical TOC (English only, repo docs only)
│
├── architecture/
│ ├── README.md ← Overview: what decisions have been made,
│ │ current system landscape
│ ├── decisions/ ← ADRs (immutable once accepted)
│ │ ├── ADR-001-rust-first.md
│ │ ├── ADR-002-trait-driven-extensibility.md
│ │ ├── ADR-003-wasm-plugin-model.md
│ │ ├── ADR-004-tool-shared-state-ownership.md (already exists)
│ │ ├── ADR-005-memory-backends.md
│ │ ├── ADR-006-cli-only-built-in-channel.md
│ │ └── ADR-007-gateway-extraction.md
│ └── diagrams/
│ ├── component-map.md ← Mermaid: crate topology
│ └── data-flow.md ← Mermaid: message lifecycle
│
├── proposals/ ← RFCs (living until accepted/rejected)
│ ├── microkernel-architecture.md (already exists)
│ └── documentation-standards.md (this document)
│
├── contributing/
│ ├── README.md
│ ├── docs-contract.md ← Replaced (see Section 9)
│ ├── pr-workflow.md
│ ├── reviewer-playbook.md
│ ├── ci-map.md
│ ├── actions-source-policy.md
│ ├── testing.md
│ ├── extension-examples.md
│ ├── change-playbooks.md
│ └── pr-discipline.md
│
├── reference/
│ ├── README.md
│ ├── api/
│ │ ├── config-reference.md
│ │ ├── providers-reference.md
│ │ └── channels-reference.md
│ └── cli/
│ └── commands-reference.md
│
├── security/
│ ├── README.md
│ ├── agnostic-security.md
│ ├── frictionless-security.md
│ ├── sandboxing.md
│ ├── audit-logging.md
│ └── security-roadmap.md
│
└── hardware/
├── README.md
├── hardware-peripherals-design.md
├── adding-boards-and-tools.md
└── datasheets/
├── nucleo-f401re.md
├── arduino-uno.md
└── esp32.md
Deleted from current structure:
docs/i18n/ ← 169 files, 2.2 MB — removed entirely
docs/maintainers/ ← project snapshots and i18n coverage maps
moved to Wiki (operational, not code-adjacent)
docs/setup-guides/ ← moved to Wiki
docs/ops/ ← moved to Wiki
README.ar.md (and 30 others) ← removed from repo root
docs/README.ar.md (and 30 others)← removed
The root of the repository becomes clean:
README.md
AGENTS.md
CHANGELOG.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
SECURITY.md
LICENSE-APACHE
LICENSE-MIT
NOTICE
Cargo.toml
Cargo.lock
... (build and config files)
No language variants. No duplicated READMEs. One authoritative English README that links to the Wiki for user guides and the docs/ tree for technical reference.
The current docs/contributing/docs-contract.md encodes the i18n parity requirement and a structure that will be obsolete after this RFC is implemented. It should be replaced in full.
The replacement governs three things: artifact classification, the repo/wiki split, and ADR governance. It says nothing about i18n.
Replacement docs-contract.md (abbreviated here for clarity; full version to be written as a follow-up PR):
# Documentation Contract
## Document Classification
Every document in `docs/` belongs to one artifact family:
- **Considerations** — principles and standards that guide decisions
- **Landscapes** — descriptions of the current system state
- **Outlines** — proposals and roadmaps for future work
- **Designs** — ADRs, API specs, and detailed technical decisions
- **Standards** — specific rules for how we build and operate
If you cannot name the family before writing, do not write yet.
## The Repo / Wiki Rule
A document lives in the repository if it would become wrong when the
code changes. It lives on the Wiki if it would not.
Reference documentation (config reference, CLI reference) lives in the
repository because it maps directly to code structures.
User guides, setup instructions, and operational how-tos live on the Wiki
because they update on their own timeline.
## ADR Governance
See docs/architecture/decisions/ for the ADR format and lifecycle rules.
Major architectural changes require an ADR before implementation begins,
not after.
## Language
All documents in this repository are written in English.
Community-maintained translations live on the GitHub Wiki.
Documentation PRs are reviewed in English only.
## Freshness
Documents should be updated in the same PR as the code change that makes
them stale. A PR that changes a configuration format must update the
config reference. A PR that adds a new command must update the CLI reference.
Proposals in docs/proposals/ are exempt — they describe intent and may
precede implementation by multiple releases.These documentation-specific standards complement the broader standards proposed in the architecture RFC.
What it is: Diátaxis (https://diataxis.fr) is a systematic framework for technical documentation that divides content into four types: tutorials, how-to guides, reference, and explanation. It is the documentation framework behind the Python documentation, Django docs, and many others. It is highly compatible with the EA Artifacts approach — they answer different questions (Diátaxis: how to structure the content of a document; EA Artifacts: what type of document is this and where does it live).
How it applies: User-facing documentation on the Wiki should follow Diátaxis structure. Code-adjacent documentation in the repository follows EA Artifacts. The two frameworks operate at different levels and do not conflict.
| Diátaxis Type | Purpose | Example in ZeroClaw | Location |
|---|---|---|---|
| Tutorial | Learning-oriented, leads through an experience | "Build your first tool plugin" | Wiki |
| How-to Guide | Goal-oriented, solves a specific problem | "Set up Telegram integration" | Wiki |
| Reference | Information-oriented, describes the machinery | Config reference, CLI reference | Repo |
| Explanation | Understanding-oriented, explains why | ADRs, architecture docs | Repo |
All documents in docs/ should include YAML frontmatter. This makes them queryable by AI tools, CI checks, and future tooling:
---
type: adr | proposal | reference | contributing | security | hardware
status: draft | proposed | accepted | deprecated | superseded
last-reviewed: YYYY-MM-DD
relates-to:
- ADR-NNN
- crates/zeroclaw-api
---A CI check should verify that all documents in docs/ have valid frontmatter. This prevents documents from being written without first declaring their type and status — enforcing the classification discipline at the tooling level.
All documentation uses CommonMark (the standardized Markdown specification) with GitHub Flavored Markdown extensions (tables, task lists, fenced code blocks, Mermaid diagrams). No custom extensions, no MDX, no ReStructuredText. Mermaid diagrams are preferred over image files for architecture diagrams because they version cleanly with the code.
What it is: Vale (https://vale.sh) is a prose linter — it checks writing style, consistency, and readability using configurable rules. It can enforce things like: always use "you" not "the user", avoid passive voice in imperative sections, use consistent terminology ("plugin" not "extension" not "module").
Why it matters: The current documentation is inconsistent in tone, terminology, and style. Some pages say "plugin", some say "module", some say "extension". Vale makes these rules automatic and enforces them at CI time, the same way Clippy enforces code quality.
The documentation migration follows the same Strangler Fig pattern as the architecture migration: incremental, always in a working state, no big-bang rewrites.
Deliverables:
- Remove all
README.*.mdfiles from the repo root (keep onlyREADME.md) - Remove
docs/i18n/entirely - Remove all non-English hub files from
docs/ - Add the
Languagessection toREADME.mdwith Wiki link - Create the GitHub Wiki with the structural skeleton (Home + top-level pages, content stubs)
- Remove the i18n parity requirement from
docs-contract.md - Add YAML frontmatter to all existing
docs/files - Create
docs/architecture/decisions/directory and move ADR-004 into it asADR-004-tool-shared-state-ownership.md
Success metrics:
- Repo root contains exactly one README file
-
docs/i18n/does not exist - All
docs/files have valid YAML frontmatter (CI-enforced) - GitHub Wiki is live and publicly linked from README
Deliverables:
- Write ADR-001 through ADR-003 and ADR-005 through ADR-007 (retroactive, see Section 6.3)
- Add a Vale configuration (
.vale.ini+ style rules) and CI check - Replace
docs-contract.mdin full with the version specified in Section 9 - Migrate
docs/setup-guides/content to the GitHub Wiki - Migrate
docs/ops/content to the GitHub Wiki - Update
SUMMARY.mdto reflect the new structure (repo-only content) - Write root-level
AGENTS.mdforcrates/zeroclaw-api(in anticipation of extraction)
Success metrics:
- ADR-001 through ADR-007 exist and are accepted
- Vale CI check passes on all docs
- Wiki has complete content for all migrated sections
- No dead links in
docs/
Deliverables:
- Write
AGENTS.mdfor each new crate as the workspace decomposes (per architecture RFC phases) - Write
docs/architecture/diagrams/component-map.md(Mermaid, reflects target crate topology) - Write
docs/architecture/diagrams/data-flow.md(Mermaid, message lifecycle) - Write the plugin SDK documentation in
docs/contributing/plugin-sdk.md - Write the WIT interface documentation alongside the
wit/files (generated from WIT + hand-written explanation) - Update the OpenAPI spec documentation as the kernel IPC API stabilizes
Success metrics:
- Every crate in the workspace has an
AGENTS.md - Architecture diagrams are Mermaid (no binary image files in docs/)
- Plugin SDK documentation is sufficient for an external contributor to write a working tool plugin
Deliverables:
- Mark ADR-001 through ADR-007 as
accepted(notproposed) once the corresponding code is shipped - Version the kernel IPC API documentation at
v1with a stability guarantee - Write the Plugin Registry governance document (who controls the registry, how plugins are reviewed, how compromised plugins are revoked)
- Publish the plugin SDK as a standalone document site (from
docs/contributing/plugin-sdk.md) - Establish the Wiki translation coordinator role (a community member who maintains the Translations page and coordinates volunteer translators)
Success metrics:
- All foundational ADRs are accepted
- Plugin SDK is complete and externally linked from the README
- Wiki has active community-maintained translations in at least two languages
- Documentation CI (frontmatter check + Vale) passes on every PR
This RFC is a proposal, not a decision. The following questions should be discussed and resolved before implementation begins.
-
Do we agree on removing i18n from the repository? This is the most visible user-facing change. Are there communities for whom this creates a genuine access problem we have not considered?
-
Who creates and maintains the GitHub Wiki? The Wiki is outside the PR process — anyone with repository access can edit it. What is the governance model? Do we want to restrict Wiki editing to collaborators, or open it fully?
-
Do we adopt Vale for prose linting? This adds a CI dependency and requires someone to own the style rules. Is the consistency benefit worth the overhead at this stage of the project?
-
Which retroactive ADRs are the highest priority? ADR-001 through ADR-007 are all valuable, but writing them takes time and requires someone with context on the original decisions. Which two or three are most urgent for onboarding new contributors?
-
Should the AGENTS.md frontmatter be formalized? The current root
AGENTS.mdis freeform. Should we define a schema for crate-levelAGENTS.mdfiles that tools can parse, or keep them as human-readable prose? -
What is the migration timeline for the Wiki? Moving
docs/setup-guides/anddocs/ops/to the Wiki means those pages will exist in two places during the transition. How do we handle the redirect period to avoid confusing users following old links?
ADR (Architecture Decision Record) — An immutable record of a significant architectural decision: the context that prompted it, what was decided, and the consequences. ADRs do not change once accepted; superseded decisions are recorded as new ADRs.
Diátaxis — A systematic framework for technical documentation structure that divides content into tutorials (learning), how-to guides (goal-oriented), reference (information), and explanation (understanding). See https://diataxis.fr.
EA Artifacts on a Page — A classification framework for enterprise architecture documents developed by Svyatoslav Kotusev. Classifies artifacts into five families: Considerations, Landscapes, Outlines, Designs, and Standards. See https://eaonapage.com.
Frontmatter — YAML metadata at the top of a Markdown file, delimited by ---. Makes documents machine-readable and queryable by tools, CI checks, and AI assistants.
Nygard Format — The ADR format introduced by Michael Nygard: three sections (Context, Decision, Consequences) that capture the essential reasoning without unnecessary ceremony.
Strangler Fig Pattern — A migration strategy in which new structure is built incrementally around the old, replacing it piece by piece rather than all at once. The system remains functional throughout the migration.
Vale — A prose linter for technical documentation. Enforces style, consistency, and readability rules at CI time, the way Clippy enforces Rust code quality. See https://vale.sh.
- Diátaxis documentation framework — https://diataxis.fr — The definitive reference for structuring technical documentation by type.
- EA Artifacts on a Page (v2.2) — https://eaonapage.com — The classification framework used in Section 3.
- "Docs for Developers" — Jared Bhatti et al. — A practical guide to technical documentation written by engineers who have maintained large documentation systems.
- Vale documentation — https://vale.sh/docs — Setup guide and configuration reference for the prose linter proposed in Section 10.
- Michael Nygard on ADRs — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions — The original post that introduced the ADR format used in Section 6.
- GitHub Wikis documentation — https://docs.github.com/en/communities/documenting-your-project-with-wikis — Reference for setting up and governing the GitHub Wiki proposed in Section 5.
This proposal was developed from direct analysis of the ZeroClaw documentation system at v0.6.8. The metrics cited (169 i18n files, 2.2 MB, 31 language README variants) are based on direct measurement. The recommendations reflect established practices in technical documentation for open source infrastructure projects, adapted to the specific constraints and goals of ZeroClaw.
Feedback, corrections, and counterproposals are welcome. Good documentation is a community effort, and the best structure is the one the team will actually maintain.