62 lines
1.4 KiB
Markdown
62 lines
1.4 KiB
Markdown
# Docs Style Guide
|
|
|
|
Date: 2026-02-16
|
|
Purpose: standardized writing and structure for canonical documentation in this repository.
|
|
|
|
## Scope
|
|
|
|
This guide applies to canonical docs in:
|
|
- `docs/`
|
|
- `docs/runbooks/`
|
|
- `config/*.md`
|
|
- root operational docs (`PROJECT-MASTER-INDEX.md`, `NODA1-SAFE-DEPLOY.md`, `NODA1-README.md`)
|
|
|
|
Legacy and snapshot docs are excluded from strict linting:
|
|
- `docs/consolidation/_node1_runtime_docs/`
|
|
- `.worktrees/`
|
|
- backup artifacts (`*.bak_*`)
|
|
|
|
## Required Structure
|
|
|
|
Every new canonical document should start with:
|
|
1. H1 title
|
|
2. `Date: YYYY-MM-DD`
|
|
3. `Purpose: ...`
|
|
|
|
Recommended sections:
|
|
1. Scope
|
|
2. Preconditions
|
|
3. Procedure / Steps
|
|
4. Verification
|
|
5. Rollback / Recovery
|
|
|
|
## Writing Rules
|
|
|
|
- Use sentence-case headings.
|
|
- Keep sections short and operational.
|
|
- Prefer explicit paths and commands.
|
|
- Mark runtime facts with concrete dates.
|
|
- Avoid mixing strategic legacy notes into canonical runbooks.
|
|
|
|
## Naming Rules
|
|
|
|
- Runbooks: `docs/runbooks/<TOPIC>_RUNBOOK.md`
|
|
- Decisions: `docs/runbooks/<TOPIC>_DECISION_YYYY-MM-DD.md`
|
|
- One-off status snapshots: include date in filename.
|
|
|
|
## Linting
|
|
|
|
Local check:
|
|
```bash
|
|
bash scripts/docs/docs_lint.sh
|
|
```
|
|
|
|
CI check:
|
|
- GitHub workflow: `.github/workflows/docs-lint.yml`
|
|
|
|
Lint scope source:
|
|
- `docs/standards/lint_scope.txt`
|
|
|
|
Note:
|
|
- Full historical docs migration is phased; lint is enforced on managed canonical scope first.
|