Erich Blume 5c79a8dbe2 Add doc-random task and documentation improvements (#98 )

## Summary
- Add `doc-random` mise task that selects a random documentation card for review
- Add how-to/knowledgebase section with review-documentation guide
- Add Caddy reference card with proxy configuration details
- Fix replication tutorial sequence (tailscale-setup now links to core-services)
- Fix "BluemeOps" typo in tailscale-setup
- Clean up obsolete zk/ directory references from doc-links

## Deployment and Testing
- [x] `mise run doc-random` works and displays a random card
- [x] `mise run doc-links` passes (all wiki-links valid)
- [x] Pre-commit hooks pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/98

2026-02-03 21:17:58 -08:00

2.2 KiB

Raw Blame History

title

Review Documentation

How to periodically review and maintain the BlumeOps knowledge base.

Quick Random Review

Select a random documentation card for review:

mise run doc-random

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

Review Checklist

When reviewing a documentation card, consider:

Check	Description
Accuracy	Is the information current and correct?
Links	Are wiki-links working? Should more be added?
Scope	Is the card appropriately sized (not too large/small)?
Category	Is it in the right section (reference/how-to/tutorial/explanation)?
Frontmatter	Are title and tags appropriate?
Related	Should 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 doc-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:

Create a feature branch
Make the edits
Run mise run doc-links to verify links
Create a PR for review

See update-documentation for publishing changes.

update-documentation - Publishing documentation changes
exploring-the-docs - Navigating the documentation

2.2 KiB Raw Blame History