Documentation Style

Use this guide when adding or changing pages in mn-docs.

Tone

• Clear
• Practical
• Friendly
• Direct

Avoid vague sentences such as "configure it as needed." Say what to configure, where to configure it, and how to verify it worked.

Page Types

MirrorNeuron docs use four page types:

Page Titles

Use action titles for guides.

Good:

• Start a two-box cluster
• Configure Redis Sentinel HA
• Create a Python-defined blueprint

Avoid:

• Cluster
• Redis stuff
• Python

Commands

Always use fenced code blocks:

mn blueprint run message_routing_trace

Include the working directory when it matters:

cd MirrorNeuron
mix test

Expected Output

Show expected output after important commands:

PONG

For commands with noisy logs, show the stable success marker:

All selected test suites passed.

Warnings

Use warnings for security, data loss, public network exposure, and irreversible cleanup.

Example:

Warning: `--purge-local` can delete Redis data. Use it only for disposable test state.

Examples

Prefer examples from checked-in blueprints:

• mn-blueprints/message_routing_trace
• mn-blueprints/python_sdk_research_pipeline
• mn-blueprints/stream_backpressure_simulation
• mn-blueprints/parallel_worker_benchmark

Folder README Standard

Most folder-level README.md files should stay quick. Put durable detail in mn-docs and link to it.

Exception: blueprint folders in mn-blueprints and otterdesk-blueprints should stay self-contained. Their README files may include local catalog, input/output, safety, and validation detail because users often inspect a blueprint folder without opening the central docs.

A quick README should include:

• one-sentence purpose;
• one or two safe first commands;
• the smallest useful validation command;
• links to the detailed guide, API reference, architecture page, or local spec.

Do not duplicate long environment-variable tables, architecture explanations, release procedures, or troubleshooting sections in non-blueprint component READMEs. Move that material to a durable page such as Component Guide, Environment Variables, Runtime Architecture, or Troubleshooting.

Links

End each page with the next useful page. Good docs should help readers continue without guessing.

Docs PR Checklist

• The page has one clear purpose.
• Commands are copy-pasteable from the stated working directory.
• Important commands include expected output.
• Security implications are called out.
• Links are relative and point to existing pages.
• Troubleshooting was updated if the change addresses a repeated failure.

Recommended CI Checks

• Markdown lint.
• Broken link checker.
• Spellcheck with project-specific vocabulary.
• Docs build check.
• Example command smoke tests for fast, non-destructive examples.

Related Pages

• Contributing
• Testing
• Troubleshooting