40 lines
809 B
Markdown
40 lines
809 B
Markdown
# Docs style guide
|
||
|
||
## Principles
|
||
|
||
- **Be concrete.** Prefer commands, examples, and “expected output” over prose.
|
||
- **Don’t invent behavior.** If unsure, link to the source file and mark it as “verify”.
|
||
- **Optimize for scanning.** Short sections, bullets, and tables.
|
||
- **Call out risk.** Anything destructive or security-sensitive should be labeled clearly.
|
||
|
||
## Markdown conventions
|
||
|
||
- Use sentence-case headings.
|
||
- Prefer fenced code blocks with a language (`bash`, `yaml`, `json`).
|
||
- For warnings/notes, use simple callouts:
|
||
|
||
```md
|
||
> **Note**
|
||
> ...
|
||
|
||
> **Warning**
|
||
> ...
|
||
```
|
||
|
||
## Common templates
|
||
|
||
### Procedure
|
||
|
||
1. Prereqs
|
||
2. Steps
|
||
3. Verify
|
||
4. Troubleshooting
|
||
|
||
### Config reference entry
|
||
|
||
- **Name**
|
||
- **Where set** (`.env`, env var, compose)
|
||
- **Default**
|
||
- **Example**
|
||
- **Notes / pitfalls**
|