Documentation Standards

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

Information architecture

Use this broad hierarchy:

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.