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 f8f11121eb Complete Phase 6: documentation cleanup and integration (#97) 
## Summary
- Delete `docs/zk/` directory - all useful content migrated to structured docs
- Delete `docs/README.md` - `docs/index.md` is now the documentation root
- Add `devpi` reference card and `use-pypi-proxy` how-to guide
- Add maintenance notes to `indri` reference (sleep prevention, passwordless sudo)
- Add iCloud Photos backup note to `borgmatic` reference
- Rewrite `zk-docs` mise task to prime AI context with key docs instead of legacy cards
- Update `CLAUDE.md` and `README.md` to remove zk references
- Update `exploring-the-docs` with AI context priming section

This completes the Diataxis documentation restructuring. All six phases are now done.

## Deployment and Testing
- [x] Pre-commit hooks pass (including doc-links validator)
- [ ] Build and deploy to docs.ops.eblu.me to verify rendering

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/97
2026-02-03 20:52:37 -08:00

3.1 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/index Tutorials]]** Learning-oriented
**[[reference/index Reference]]** Information-oriented
**[[how-to/index How-to]]** Task-oriented
**[[explanation/index Explanation]]** Understanding-oriented

Quick Paths by Audience

For Erich (Owner)

You probably want quick access to operational details:

  • how-to/index for common operations (deploy, troubleshoot, update ACLs)
  • reference/index 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
  • reference/index 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:

For Contributors

Getting started with changes:

For Replicators

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

  • replicating-blumeops provides the overview
  • explanation/index covers architecture and design rationale
  • The replication/ tutorials go deep on components
  • Reference pages show specific configuration choices

Using Wiki Links

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

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

When reading on the web (docs.ops.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

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