Skip to main content

Documentation Policy

Last reviewed: 2026-06-13
Maintained by: Engineering

Purpose​

Keep documentation trustworthy, safe to share, and useful for engineers, product stakeholders, and public technical readers.

Mandatory Same-PR Documentation Updates​

Documentation must be updated in the same PR when any of the following change:

  • script name or script behavior
  • environment variable contract
  • port mapping
  • migration flow or schema workflow
  • app startup flow

PR Requirement​

Every PR must include either:

  1. Updated documentation, or
  2. An explicit statement in PR description:

No documentation impact: <reason>

Documentation Ownership and Freshness​

Each maintained doc should include metadata at top:

  • Last reviewed: YYYY-MM-DD
  • Owner: <team/person> or Maintained by: Engineering

Canonical Public Entry Point​

Primary public docs entrypoint:

When adding a new public-facing doc, link it from the homepage or an existing public navigation section.

Documentation Safety​

Document the current product and technical setup in a way that is useful for engineering, product work, and public technical overview, but do not publish sensitive operational detail.

OK to document:

  • app boundaries and responsibilities
  • implemented feature surfaces
  • environment variable names and safe placeholder examples
  • external service purpose and ownership
  • security controls at a high level

Must stay out of docs:

  • real secrets, DSNs, API keys, tokens, private URLs, account IDs, bucket names, or internal credentials
  • real dashboard links when they are private or operationally sensitive
  • temporary verification/test routes presented as permanent product features
  • overly detailed security bypass, abuse-tuning, or exploit-oriented instructions

Rules:

  • use placeholders or blank values for sensitive examples
  • prefer high-level descriptions of security controls over step-by-step internal mechanics
  • if a route or page exists only for temporary verification, do not document it as a stable feature
  • public entry pages and main navigation should prioritize application overview, implemented capabilities, architecture, and safe reference material over internal runbooks