Skip to content

Documentation Standards

Audience model

Persona A — Alex, Platform/Infrastructure Engineer

Background: Manages GKE clusters, Terraform/OpenTofu modules, GitOps pipelines, and GCP IAM. Comfortable with Kubernetes, Helm, Workload Identity, OTEL Collector configuration, and CI/CD workflows.

What makes a doc succeed for Alex:

  • Exact values: resource names, namespace names, IAM role strings, environment variables
  • Complete, copy-adaptable commands and configuration snippets
  • Clear "why this design?" rationale for non-obvious decisions
  • Cross-references to related capabilities, guides, and runbooks

What breaks the experience:

  • Paragraphs explaining foundational Kubernetes or GCP concepts
  • Incomplete examples that say "follow the same pattern" without showing it
  • Missing rollback or escalation steps in operational procedures

Persona B — Sam, Application/Service Engineer

Background: Writes backend services (Go, Node.js, Python) deployed to the IoT platform. Familiar with Docker and basic kubectl commands. Has not managed a GKE cluster, written Terraform, or configured IAM policies.

What makes a doc succeed for Sam:

  • "What is X?" explanations before "how to configure X"
  • Analogies to familiar concepts (HTTP requests, environment variables, file permissions)
  • Jargon defined inline on first use (GSA, KSA, OTLP, GitOps)
  • Diagrams showing component relationships before diving into detail

What breaks the experience:

  • Docs that open with infrastructure configuration before explaining the capability
  • Assuming Workload Identity, OTEL Collector, or Helm are already understood
  • Missing the big-picture diagram before the detail

Section intent

Section Primary persona Main question
Platform Both Why is the platform designed this way?
Capabilities Both What contract spans infra and application changes?
Services Alex (primary), Sam (secondary) What does this service depend on and who owns it?
Guides Alex (primary), Sam (secondary) How do I execute this task correctly?
Runbooks Alex only How do I diagnose and recover quickly?
Reference Both What is the canonical exact detail?

When a page serves both personas, structure it context-first, configuration-second: the "why" and "what is this?" section at the top serves Sam; the precise values and commands below serve Alex.

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.