microdao-daarion/docs/standards/DOCS_STYLE_GUIDE.md

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 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.