Docs Maintenance

Use this page before releases and when changing CRDs, Helm values, metrics, dashboards, Events, or logs.

Ownership

Area	Owner
Platform install and chart docs	Platform team
CRD reference and behavior docs	Operator maintainers
Backup and restore docs	Database/infra team
App integration docs	Application platform team
Security model	Security and operator maintainers
Runbooks	On-call owners

Standard task page structure

1. Overview.
2. Prerequisites.
3. Example manifest or command.
4. Apply.
5. Verify.
6. Troubleshoot.
7. Next steps.

Standard reference page structure

1. What this page covers.
2. Concepts.
3. Field or behavior reference.
4. Examples.
5. Failure modes.
6. Related pages.

Terminology

Use these terms consistently:

Preferred	Avoid
primary	master
replica	slave
site	datacenter unless specifically referring to a datacenter
active site	current writable site
standby site or replica site	passive promotion candidate
dr-only site	passive site that is never auto-promoted
failover group	cluster, unless discussing Kubernetes clusters

Example names

Item	Default example
Failover group	orders
Namespace	orders
Sites	iad, pdx
DNS name	orders.az.example.com
Operator namespace	bloodraven
StorageClass	fast-ssd

Release checklist

• Regenerate API docs if fields changed.
• Check Helm values references.
• Check dashboard list and UIDs.
• Check metrics list and alert names.
• Check Event and log schema docs.
• Check upgrade policy.
• Check known limitations.
• Build docs locally with npm run build from docs/.
• Verify llms-full.txt with npm run verify:llms from docs/.
• Review examples against the release tag.

Publishing automation

GitHub Actions treats the documentation site as a release artifact:

Gate	Workflow	What it proves
Pull requests and main pushes	.github/workflows/ci.yml	Docusaurus builds and llms-full.txt includes every page under docs/docs/.
Release tags	.github/workflows/release.yml	The release candidate passes the same docs build and llms-full.txt coverage check before images and charts publish.
main pushes	ReadTheDocs project setting	ReadTheDocs watches the repository and publishes the latest version from the merged commit.
Nightly and manual runs	.github/workflows/docs-link-check.yml	The public site under https://bloodraven.readthedocs.io/en/latest/ has no same-site broken links.

Keep the ReadTheDocs project connected to the repository so merged changes publish without a GitHub Actions token or custom API trigger.

Validation checklist

• YAML examples use shipstream.io/v1alpha1.
• Required CRD fields are present.
• Deprecated fields are labelled as deprecated.
• Command blocks use explicit namespaces.
• Example passwords are clearly placeholders.
• Helm values match charts/bloodraven/values.yaml.
• Internal links build cleanly.