Home A - Z
Page Index

Blame

e23584 Dan Alexander 2026-09-14 10:46:55
Add company wiki standards and VoxelCore docs This change establishes the shared company knowledge structure, governance, engineering, security, and incident/change standards. It also adds the VoxelHorizons product tree with a complete VoxelCore documentation set covering architecture, operations, authoring, version support, resource pack compilation, runtime reloads, and testing/release workflows.
1 
# Documentation Standards
2
3
These conventions keep the wiki predictable as more Soatrix products are added.
4
5
## Information architecture
6
7
Use this broad hierarchy:
8
9
```text
10
Home
11
├── Company
12
│ ├── shared standards
13
│ ├── governance
14
│ └── operating practices
15
├── Products
16
│ └── <product family>
17
│ └── <product or service>
18
│ ├── overview/current status
19
│ ├── user or operator guides
20
│ ├── architecture/developer reference
21
│ └── roadmap
22
└── Templates
23
```
24
25
Do not create a new top-level category when an existing one fits.
26
27
## Naming
28
29
- Give every page one clear `# H1` title.
30
- Keep Git filenames and directories simple, lower-case and URL-safe.
31
- Prefer descriptive page names over generic names such as `notes` or `misc`.
32
- Use the first heading for the human-readable title.
33
34
## Writing rules
35
36
- State exact versions, paths and dates when they affect correctness.
37
- Put commands and configuration in fenced code blocks.
38
- Explain destructive or irreversible effects immediately before the action.
39
- Separate **current behaviour**, **known limitations** and **planned work**.
40
- Prefer one canonical explanation and link to it rather than copying the same rule across pages.
41
- Keep troubleshooting symptom-driven: symptom → likely cause → check → recovery.
42
43
## Repository-backed products
44
45
A well-maintained product tree should normally contain:
46
47
- `Index` — purpose and navigation;
48
- `Current Status` — baseline commit, supported surface and notable recent changes;
49
- `Getting Started` — minimum path to a working system;
50
- `Architecture` — boundaries and data flow;
51
- configuration and command/reference pages;
52
- build/testing/release information;
53
- operations/troubleshooting;
54
- roadmap/scope.
55
56
Use [[Templates/Product-Documentation]] when starting a new product.