Documentation Standards

Audience model

Persona A: Infrastructure engineer

• Wants precise implementation details
• Needs exact values, names, and commands
• Uses reference and guides heavily

Persona B: Application engineer

• Wants clear conceptual understanding first
• Needs practical constraints and integration patterns
• Uses concepts and capability pages heavily

Section intent

Section	Main question
Platform	Why is the platform designed this way?
Capabilities	What contract spans infra and application changes?
Services	What does this service depend on and who owns it?
Guides	How do I execute this task correctly?
Runbooks	How do I diagnose and recover quickly?
Reference	What is the canonical exact detail?

Required page frontmatter

Every page must include:

• title
• description
• owners
• audience
• doc_status
• last_reviewed
• tags
• source_repos

See Metadata Schema for exact format.

Content rules

1. Define the reader and purpose at the top.
2. Use explicit contracts for cross-team capabilities.
3. Prefer copy-adaptable examples over abstract guidance.
4. Keep source-of-truth links to repo paths for implementation details.
5. Avoid hidden assumptions and unexplained jargon.