Erich Blume
d01a165b91
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>
123 lines
3.2 KiB
Markdown
123 lines
3.2 KiB
Markdown
---
|
|
title: Review Documentation
|
|
modified: 2026-02-09
|
|
last-reviewed: 2026-03-07
|
|
tags:
|
|
- how-to
|
|
- documentation
|
|
- maintenance
|
|
---
|
|
|
|
# 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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
---
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Related
|
|
|
|
- [[update-documentation]] - Publishing documentation changes
|
|
- [[exploring-the-docs]] - Navigating the documentation
|