Erich Blume d01a165b91 Add docs-preview task and visual preview step to doc review

New `mise run docs-preview <card>` task builds docs via Dagger and serves
them locally in the production quartz container (image parsed from ArgoCD
kustomization), opening the browser directly to the specified card.
Container auto-cleans after 1 hour.

Also updates docs-review checklist and review-documentation how-to to
reference the visual preview workflow.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-11 18:04:01 -07:00

3.2 KiB

Raw Blame History

title

modified

last-reviewed

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:

mise run tailnet-preview  # Tailscale ACLs
mise run dns-preview      # DNS (Gandi)

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

Visual Preview

After reviewing and editing a card, visually verify the rendered output.

Quick scan (agent): Have the agent display the card with bat for a terminal-based visual check.

Full rendered preview: Build the entire Quartz docs site locally and open directly to the card:

mise run docs-preview how-to/knowledgebase/review-documentation

This builds the docs with Dagger, serves them on localhost:8484, and opens the browser to the specified card. Press Ctrl-C to stop. Accepts paths with or without the .md suffix.

Making Changes

If a card needs updates, classify the change (see agent-change-process):

C0 (small fix): Edit, commit directly to main
C1/C2 (larger changes): Create a feature branch and PR

Link validation runs automatically via prek on commit.

See update-documentation for publishing changes.

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

3.2 KiB Raw Blame History