Documentation Style
Author and review implementation-backed MirrorNeuron documentation.
Documentation Style
Use this guide when you create or substantially update a MirrorNeuron documentation page. Documentation is part of the product: it must help a named reader reach a safe, observable outcome without guessing.
Write a brief before drafting
Record the following in the issue, pull request, or page draft:
| Item | What to define |
|---|---|
| Reader | Evaluator, application developer, blueprint author, operator, integrator, contributor, or maintainer. |
| Outcome | One observable result the reader can achieve. |
| Page type | Tutorial, how-to, reference, explanation, troubleshooting, migration, or decision record. |
| Scope | The exact command, API, component, workflow, or behavior covered. |
| Out of scope | Nearby topics intentionally excluded. |
| Sources of truth | Code, CLI help, tests, schemas, generated API definitions, or release artifacts used to verify claims. |
| Validation | The documentation build and the smallest relevant product command or test. |
Keep page types distinct
| Type | Reader need | Required content |
|---|---|---|
| Tutorial | Learn a complete first experience. | Prerequisites, ordered steps, verification, cleanup, and next steps. |
| How-to | Complete one operational task. | Assumptions, procedure, verification, rollback, and symptom-led help. |
| Reference | Look up exact facts. | Declared scope, exact syntax or fields, defaults, side effects, errors, and small examples. |
| Explanation | Understand a design choice. | Problem, mental model, boundaries, guarantees, non-guarantees, failures, and tradeoffs. |
| Troubleshooting | Recover from an observable failure. | Symptom, likely causes, read-only diagnostics, resolution, verification, and escalation evidence. |
Do not turn a reference page into a tutorial or hide operational procedures inside architecture prose. Link to the canonical page instead.
Commands and examples
- Use fenced
bash,json,python,text, or other appropriate code blocks. - State the working directory when it matters.
- Use only commands verified against CLI help, tests, schemas, or a representative runtime.
- Use a checked-in example only when its requirements and safety boundaries are documented.
- Use placeholders such as
<job_id>and define them immediately after the block. - Show a stable success marker only when it is verified. Otherwise tell the reader which command exit status or observable state proves success.
- Include cleanup for jobs, services, ports, generated files, or persistent state created by the procedure.
Accuracy and safety
- Use the implementation as the source of truth. Never infer a command, default, port, guarantee, or compatibility policy.
- Keep one canonical page for durable facts such as CLI syntax, API contracts, environment variables, and manifest fields.
- State what a feature does not guarantee, especially for retries, external side effects, local execution, sandboxing, privacy, and clustering.
- Warn before actions that delete data, expose listeners, pass secrets into worker code, execute unreviewed bundles, or join a cluster trust domain.
- Do not publish agent instructions, release procedures, templates, obsolete diagrams, or references to removed components as product documentation.
Review checklist
- The title, reader, outcome, and primary page type are clear in the opening screen.
- Important claims cite or were checked against an authoritative implementation source.
- Commands, links, examples, and stated defaults were validated.
- Each state-changing procedure includes verification and applicable cleanup or rollback.
- Security, data movement, secrets, network exposure, and non-guarantees are visible where relevant.
- Related pages point to the next useful action.