From 124ffb60d726b4a03356a89444e547d8a9670507 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Tue, 3 Feb 2026 21:08:49 -0800 Subject: [PATCH] Add doc-random mise task for documentation review - New mise task selects a random doc card for periodic review - Add how-to/knowledgebase section with review-documentation guide - Clean up obsolete zk/ directory references from doc-links Co-Authored-By: Claude Opus 4.5 --- docs/changelog.d/random-doc-review.feature.md | 1 + docs/how-to/index.md | 6 ++ .../knowledgebase/review-documentation.md | 58 +++++++++++++ docs/tutorials/ai-assistance-guide.md | 1 + mise-tasks/doc-links | 10 +-- mise-tasks/doc-random | 84 +++++++++++++++++++ 6 files changed, 155 insertions(+), 5 deletions(-) create mode 100644 docs/changelog.d/random-doc-review.feature.md create mode 100644 docs/how-to/knowledgebase/review-documentation.md create mode 100755 mise-tasks/doc-random diff --git a/docs/changelog.d/random-doc-review.feature.md b/docs/changelog.d/random-doc-review.feature.md new file mode 100644 index 0000000..641a9cc --- /dev/null +++ b/docs/changelog.d/random-doc-review.feature.md @@ -0,0 +1 @@ +Add doc-random mise task for random documentation review diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 4f5ab11..f5f253e 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -28,6 +28,12 @@ Task-oriented instructions for common BlumeOps operations. These guides assume y |-------|-------------| | [[update-documentation]] | Publish docs via build-blumeops workflow | +## Knowledge Base + +| Guide | Description | +|-------|-------------| +| [[review-documentation]] | Periodically review and maintain documentation | + ## Operations | Guide | Description | diff --git a/docs/how-to/knowledgebase/review-documentation.md b/docs/how-to/knowledgebase/review-documentation.md new file mode 100644 index 0000000..769fc3e --- /dev/null +++ b/docs/how-to/knowledgebase/review-documentation.md @@ -0,0 +1,58 @@ +--- +title: review-documentation +tags: + - how-to + - documentation + - maintenance +--- + +# Review Documentation + +How to periodically review and maintain the BlumeOps knowledge base. + +## Quick Random Review + +Select a random documentation card for review: + +```bash +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? | + +## 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: + +1. Create a feature branch +2. Make the edits +3. Run `mise run doc-links` to verify links +4. Create a PR for review + +See [[update-documentation]] for publishing changes. + +## Related + +- [[update-documentation]] - Publishing documentation changes +- [[exploring-the-docs]] - Navigating the documentation diff --git a/docs/tutorials/ai-assistance-guide.md b/docs/tutorials/ai-assistance-guide.md index fd67968..b6dbcc3 100644 --- a/docs/tutorials/ai-assistance-guide.md +++ b/docs/tutorials/ai-assistance-guide.md @@ -88,6 +88,7 @@ BlumeOps operations are driven by mise tasks. Run `mise tasks` to list all avail | `doc-links` | Validate wiki-links in documentation | | `doc-titles` | Check for duplicate doc titles | | `doc-filenames` | Check for duplicate doc filenames | +| `doc-random` | Select a random doc card for review | | `indri-runner-logs` | View Forgejo workflow logs from local runner | For ArgoCD operations, use the `argocd` CLI directly: diff --git a/mise-tasks/doc-links b/mise-tasks/doc-links index 7c463f0..625c9ff 100755 --- a/mise-tasks/doc-links +++ b/mise-tasks/doc-links @@ -7,7 +7,7 @@ """Validate that all wiki-links in documentation point to existing files. This script scans all markdown files in the docs/ directory (excluding -changelog.d/ and zk/), extracts wiki-links, and verifies each link target +changelog.d/), extracts wiki-links, and verifies each link target exists as a filename or path in the documentation. Wiki-link formats supported: @@ -61,9 +61,9 @@ def main() -> int: # Track which filenames are ambiguous (appear multiple times) filename_counts: dict[str, list[str]] = {} - # Scan all markdown files (excluding zk/ and changelog.d/) + # Scan all markdown files (excluding changelog.d/) for md_file in DOCS_DIR.rglob("*.md"): - if "changelog.d" in md_file.parts or "zk" in md_file.parts: + if "changelog.d" in md_file.parts: continue # Track filename occurrences filename = md_file.stem @@ -86,9 +86,9 @@ def main() -> int: broken_links: list[tuple[str, int, str]] = [] ambiguous_links: list[tuple[str, int, str, list[str]]] = [] - # Scan all markdown files for wiki-links (excluding zk/ and changelog.d/) + # Scan all markdown files for wiki-links (excluding changelog.d/) for md_file in sorted(DOCS_DIR.rglob("*.md")): - if "changelog.d" in md_file.parts or "zk" in md_file.parts: + if "changelog.d" in md_file.parts: continue rel_path = str(md_file.relative_to(DOCS_DIR)) diff --git a/mise-tasks/doc-random b/mise-tasks/doc-random new file mode 100755 index 0000000..01a584d --- /dev/null +++ b/mise-tasks/doc-random @@ -0,0 +1,84 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.12" +# dependencies = ["rich>=13.0.0"] +# /// +#MISE description="Select a random documentation card for review" +"""Select a random documentation card for review. + +This script scans all markdown files in the docs/ directory (excluding +changelog.d/), selects one at random, and displays it for review. + +Useful for periodic knowledge base maintenance and verification. + +Usage: mise run doc-random +""" + +import random +import sys +from pathlib import Path + +from rich.console import Console +from rich.markdown import Markdown +from rich.panel import Panel + +DOCS_DIR = Path(__file__).parent.parent / "docs" + + +def get_all_docs() -> list[Path]: + """Get all documentation markdown files, excluding changelog.d.""" + docs = [] + for md_file in DOCS_DIR.rglob("*.md"): + # Skip changelog fragments + if "changelog.d" in md_file.parts: + continue + docs.append(md_file) + return docs + + +def main() -> int: + console = Console() + + docs = get_all_docs() + if not docs: + console.print("[bold red]No documentation files found![/bold red]") + return 1 + + # Select a random document + selected = random.choice(docs) + rel_path = selected.relative_to(DOCS_DIR) + + # Display header + console.print() + console.print(Panel( + f"[bold cyan]{rel_path}[/bold cyan]\n" + f"[dim]{len(docs)} total docs in knowledge base[/dim]", + title="[bold]Random Documentation Card[/bold]", + border_style="cyan", + )) + console.print() + + # Display the file content + content = selected.read_text() + console.print(Markdown(content)) + + # Review checklist + console.print() + console.print(Panel( + "[bold]Review Checklist:[/bold]\n\n" + "• Is the information accurate and up-to-date?\n" + "• Are there broken or missing wiki-links?\n" + "• Should this card link to other related cards?\n" + "• Is the card too large and should be split?\n" + "• Is the card too small and should be merged?\n" + "• Does the frontmatter (tags, title) make sense?\n" + "• Is the card in the correct category (reference/how-to/etc)?", + title="[bold yellow]Review Guidance[/bold yellow]", + border_style="yellow", + )) + + return 0 + + +if __name__ == "__main__": + sys.exit(main())