eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/tutorials/exploring-the-docs.md
Erich Blume b5746e62c2 Add migration plan for Forgejo brew-to-source transition (#140) 
## Summary
- Add `docs/how-to/plans/migrate-forgejo-from-brew.md` — full Diataxis-style plan covering background, one-time migration steps, Ansible role changes (with exact code), verification checklist, and future considerations
- Add `docs/how-to/plans/plans.md` — new plans subdirectory index for upcoming migration/transition plans
- Update `docs/how-to/how-to.md` with a Plans section
- Update `docs/tutorials/exploring-the-docs.md` to mention plans in the doc structure table and quick-path sections for Owner and AI audiences

## Test plan
- [x] `docs-check-links` passes
- [x] `docs-check-index` passes
- [x] All pre-commit hooks pass

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/140
2026-02-10 10:18:53 -08:00

3.3 KiB
Raw Blame History

title tags
Exploring the Docs
tutorials
getting-started

Exploring the Documentation

Audiences: All (Owner, AI, Reader, Contributor, Replicator)

This guide explains how the BlumeOps documentation is organized and how to find what you need.

Documentation Structure

The docs follow the Diataxis framework:

Section Purpose When to Use
**[[tutorials Tutorials]]** Learning-oriented
**[[reference Reference]]** Information-oriented
**[[how-to How-to]]** Task-oriented
**[[plans Plans]]** Future work
**[[explanation Explanation]]** Understanding-oriented

Quick Paths by Audience

For Erich (Owner)

You probably want quick access to operational details:

  • how-to guides for common operations (deploy, troubleshoot, update ACLs)
  • plans captures migration and transition plans for future execution
  • reference has service URLs, commands, and config locations
  • ai-assistance-guide explains how to work effectively with Claude
  • Run mise run zk-docs to prime AI context with key documentation

For Claude/AI Agents

Context for effective assistance:

  • Read ai-assistance-guide for operational conventions
  • plans has migration plans designed for AI-executed sessions
  • reference has the technical specifics you'll need
  • The repo's CLAUDE.md has critical rules (especially the kubectl context requirement)

For External Readers

Understanding what this is:

  • explanation covers the "why" behind design decisions
  • reference shows what's actually running
  • Browse service pages to see specific implementations

For Contributors

Getting started with changes:

  • contributing walks through the workflow
  • how-to guides for specific tasks (deploy services, add roles)
  • reference tells you where things live

For Replicators

Replicators are people who want to build their own similar homelab GitOps setup, using BlumeOps as inspiration.

  • replicating-blumeops provides the overview, with linked tutorials that go deep on individual components
  • explanation covers architecture and design rationale
  • Reference pages show specific configuration choices

Using Wiki Links

Documentation uses [[wiki-links]] for cross-references:

  • [[service-name]] links to a reference page
  • [[page|Display Text]] customizes the link text

When reading on the web (docs.eblu.me), these render as clickable links. The backlinks panel shows what references each page.

Pre-commit hooks automatically validate that all wiki-links point to existing files and that link targets are unambiguous.

AI Context Priming

The zk-docs mise task concatenates key documentation files for AI context:

mise run zk-docs -- --style=header --color=never --decorations=always

This outputs the AI assistance guide, reference index, how-to index, architecture overview, and tutorials index - providing Claude with essential context for BlumeOps operations.

Related