Skip to main content

Documentation Standards

These standards apply to Iron Horse product knowledgebase content.

Source of truth​

  • Docs should be kept in Git as Markdown/MDX.
  • If a system changes, update docs in the same workstream.
  • If production differs from intended architecture, document production reality first and mark cleanup separately.

Required evidence​

Operational docs should include:

  • verified target URLs/instances/services
  • commands or probes used
  • deployment status
  • rollback path
  • caveats and known unhealthy/stale components

Secrets policy​

Never commit or paste:

  • AWS access keys
  • bearer tokens
  • private keys
  • passwords
  • service account JSON
  • raw credential URLs

It is acceptable to document secret locations, for example:

AWS SSM SecureString /path/to/parameter
GitHub Actions secret SECRET_NAME

Branching and promotion​

For BIRCH work, agents must follow this mandate:

staging → feature/work branch → staging merge → staging testing → approved-hours production promotion

Rules:

  • Start from staging.
  • Create a new feature/work branch from staging.
  • Merge completed work back into staging for testing.
  • Promote to production/main only after staging testing is complete.
  • Production promotion happens only during Iron Horse approved hours.
  • Never develop from or push directly to main / master / production unless Derek explicitly approves an emergency exception.

Enhancement docs​

Every meaningful enhancement should update:

  • product overview if behavior changed
  • API docs if routes/contracts changed
  • architecture docs if topology changed
  • runbooks if deployment/ops changed
  • enhancement log with final verification evidence