# Documentation Standards

These conventions keep the wiki predictable as more Soatrix products are added.

## Information architecture

Use this broad hierarchy:

```text
Home
├── Company
│   ├── shared standards
│   ├── governance
│   └── operating practices
├── Products
│   └── <product family>
│       └── <product or service>
│           ├── overview/current status
│           ├── user or operator guides
│           ├── architecture/developer reference
│           └── roadmap
└── Templates
```

Do not create a new top-level category when an existing one fits.

## Naming

- Give every page one clear `# H1` title.
- Keep Git filenames and directories simple, lower-case and URL-safe.
- Prefer descriptive page names over generic names such as `notes` or `misc`.
- Use the first heading for the human-readable title.

## Writing rules

- State exact versions, paths and dates when they affect correctness.
- Put commands and configuration in fenced code blocks.
- Explain destructive or irreversible effects immediately before the action.
- Separate **current behaviour**, **known limitations** and **planned work**.
- Prefer one canonical explanation and link to it rather than copying the same rule across pages.
- Keep troubleshooting symptom-driven: symptom → likely cause → check → recovery.

## Repository-backed products

A well-maintained product tree should normally contain:

- `Index` — purpose and navigation;
- `Current Status` — baseline commit, supported surface and notable recent changes;
- `Getting Started` — minimum path to a working system;
- `Architecture` — boundaries and data flow;
- configuration and command/reference pages;
- build/testing/release information;
- operations/troubleshooting;
- roadmap/scope.

Use [[Templates/Product-Documentation]] when starting a new product.