BlumeOps Docs

Review Documentation

2 min read

Review Documentation

How to periodically review and maintain the BlumeOps knowledge base.

Quick Random Review

Select a random documentation card for review:

mise run docs-review-random

This displays a random card with a review checklist to guide your assessment.

Review Checklist

When reviewing a documentation card, consider:

CheckDescription
AccuracyIs the information current and correct?
LinksAre wiki-links working? Should more be added?
ScopeIs the card appropriately sized (not too large/small)?
CategoryIs it in the right section (reference/how-to/tutorial/explanation)?
FrontmatterAre title and tags appropriate?
RelatedShould it link to related cards?

Verify Deployed State

For service reference cards, verify the documentation matches reality:

ArgoCD Apps (Kubernetes services)

Check if the app is synced and healthy:

argocd app get <app-name>
argocd app diff <app-name>  # Show pending changes

If out of sync, either the docs are stale or a deployment is pending.

Ansible Roles (indri services)

Check if the role applies idempotently (no changes needed):

mise run provision-indri -- --tags <role> --check --diff

If changes would be made, either the docs are stale or the host has drifted.

Pulumi (Tailscale ACLs, DNS)

Check for drift:

# Tailscale ACLs
cd pulumi/tailscale && pulumi preview
 
# DNS (Gandi)
cd pulumi/gandi && pulumi preview

If changes are pending, investigate whether docs or infrastructure is stale.

When to Review

Consider running mise run docs-review-random during:

  • Start of work sessions (quick maintenance)
  • After major infrastructure changes (verify docs reflect reality)
  • When learning the system (random exploration)

Making Changes

If a card needs updates:

  1. Create a feature branch
  2. Make the edits
  3. Run mise run docs-check-links to verify links
  4. Create a PR for review

See update-documentation for publishing changes.

Graph View

Backlinks