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 <noreply@anthropic.com>
This commit is contained in:
parent
f88da51e23
commit
124ffb60d7
6 changed files with 155 additions and 5 deletions
1
docs/changelog.d/random-doc-review.feature.md
Normal file
1
docs/changelog.d/random-doc-review.feature.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add doc-random mise task for random documentation review
|
||||
|
|
@ -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 |
|
||||
|
|
|
|||
58
docs/how-to/knowledgebase/review-documentation.md
Normal file
58
docs/how-to/knowledgebase/review-documentation.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue