# Documentation Style (/docs/documentation-style)



# Documentation Style [#documentation-style]

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

## Tone [#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 [#page-types]

MirrorNeuron docs use four page types:

| Type         | Purpose                      | Examples                                                                          |
| ------------ | ---------------------------- | --------------------------------------------------------------------------------- |
| Tutorial     | Walk through a complete path | [Quickstart](quickstart.md)                                                       |
| How-to guide | Solve one task               | [Redis High Availability](redis-ha.md), [Cluster Guide](cluster.md)               |
| Reference    | Provide exact facts          | [CLI Reference](cli.md), [Environment Variables](env_variables.md), [API](api.md) |
| Explanation  | Explain design and tradeoffs | [Runtime Architecture](runtime-architecture.md), [Security Model](security.md)    |

## Page Titles [#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 [#commands]

Always use fenced code blocks:

```bash
mn blueprint run message_routing_trace
```

Include the working directory when it matters:

```bash
cd MirrorNeuron
mix test
```

## Expected Output [#expected-output]

Show expected output after important commands:

```text
PONG
```

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

```text
All selected test suites passed.
```

## Warnings [#warnings]

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

Example:

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

## Examples [#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 [#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](component-guide.md), [Environment Variables](env_variables.md),
[Runtime Architecture](runtime-architecture.md), or
[Troubleshooting](troubleshooting.md).

## Links [#links]

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

## Docs PR Checklist [#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 [#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 [#related-pages]

* [Contributing](contributing.md)
* [Testing](testing.md)
* [Troubleshooting](troubleshooting.md)