Erich Blume dc46eb7def Update all docs titles to human-readable (#117 )

## Summary
- Updated frontmatter `title:` in all 63 doc cards from slug-case to human-readable (e.g. `borgmatic` → `Borgmatic`, `ai-assistance-guide` → `AI Assistance Guide`)
- Titles now closely match file stems so `[[wiki-links]]` render naturally without alternate anchor text
- Corrected titles that diverged from stems (e.g. `host-inventory` → `Hosts`, `grafana-alloy` → `Alloy`, `argocd-applications` → `Apps`)
- Deleted `title-test-alpha.md` and `title-test-beta.md` test cards and removed their reference index entry

## Deployment and Testing
- [x] `docs-check-links` passes — all wiki-links valid
- [x] `docs-check-index` passes
- [x] `docs-check-filenames` passes
- [ ] Verify titles render correctly on docs site after deploy

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

2026-02-07 21:44:57 -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 docs-review-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 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:

Create a feature branch
Make the edits
Run mise run docs-check-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