Erich Blume
9e361cf38f
## Summary - New `docs-review` mise task replaces `docs-review-random` — sorts docs by `last-reviewed` frontmatter field (never-reviewed first, then oldest) - Updated review-documentation how-to to explain the new workflow and how to mark cards as reviewed - Updated ai-assistance-guide task table to reference `docs-review` ## Test plan - [x] `mise run docs-review` runs and shows staleness table + most stale doc - [x] `mise run docs-review -- --limit 5` respects the limit flag - [x] All pre-commit checks pass (links, index, filenames) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/129
2.5 KiB
| title | tags | |||
|---|---|---|---|---|
| Review Documentation |
|
Review Documentation
How to periodically review and maintain the BlumeOps knowledge base.
Review by Staleness
Show docs sorted by when they were last reviewed (most stale first):
mise run docs-review
This reads the last-reviewed frontmatter field from each card. Cards without the field are treated as never-reviewed and appear at the top. The script shows a staleness table and then displays the most stale card with a review checklist.
To show more entries in the table:
mise run docs-review -- --limit 30
Marking a Card as Reviewed
After reviewing a card, add or update the last-reviewed field in its frontmatter:
---
title: Some Card
last-reviewed: 2026-02-09
tags:
- reference
---
Commit this change alongside any fixes you make during the review.
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.
Making Changes
If a card needs updates:
- Create a feature branch
- Make the edits
- Run
mise run docs-check-linksto verify links - Create a PR for review
See update-documentation for publishing changes.
Related
- update-documentation - Publishing documentation changes
- exploring-the-docs - Navigating the documentation