Documentation Quality Standards

This guide defines the writing and maintenance standards for AuroraSOC documentation.

Quality Goal

Every page should be useful for:

• A beginner who needs to accomplish a task safely
• A professional who needs depth, precision, and implementation detail

Writing Model (Layered by Depth)

Each major page should include these layers in order:

1. Plain-language summary
2. Step-by-step workflow
3. Advanced details and constraints
4. Failure modes and troubleshooting
5. Related pages and next steps

Required Page Sections

For setup, architecture, and integration pages, include all of these:

• When to use this page
• Prerequisites
• Happy-path walkthrough
• Verification checklist
• Common failure modes
• Links to deeper references

Accuracy Rules

1. Prefer source-linked facts over memory.
2. Avoid stale fixed counts unless they are tested or generated.
3. Keep one canonical source for each fact family:
   • Runtime versions: pyproject.toml, dashboard/package.json, docs/package.json
   • Agents and ports: aurorasoc/agents/factory.py, aurorasoc/config/settings.py
   • API behavior: FastAPI OpenAPI and route implementations

Language Rules

• Use direct, plain English first.
• Define domain terms before using acronyms.
• Use consistent terms for the same concept across pages.
• Keep examples realistic and runnable.
• Explain why, not only what.

Code and Command Examples

• Commands must run as written on Linux.
• Include context for where to run commands.
• Avoid placeholder output unless clearly labeled.
• Prefer copy-safe commands.

Beginner Experience Checklist

• Can a first-time user complete the page without external help?
• Is there at least one end-to-end example?
• Are expected results stated after each major step?
• Is troubleshooting provided for top failure cases?

Professional Experience Checklist

• Are assumptions explicit?
• Are tradeoffs and constraints explained?
• Are security implications called out?
• Are observability and validation paths documented?

Definition of Done for Docs PRs

A docs pull request is complete when:

1. Facts are validated against code.
2. Internal links are valid.
3. The page follows layered structure.
4. At least one verification path is included.
5. Build passes with strict link checks.

Review Rubric

Score each page from 1 to 5:

• Correctness
• Clarity
• Completeness
• Actionability
• Maintainability

Any category below 4 must be improved before merge.