Expand docs/README.md with full restructuring plan
Add comprehensive phased plan for documentation restructuring: - Phase 1: Foundation (current) - zk migration, tooling selection - Phase 2: Tutorials - learning-oriented content - Phase 3: How-to Guides - task-oriented instructions - Phase 4: Reference - technical descriptions - Phase 5: Explanation - concepts and decisions - Phase 6: Integration & Cleanup Also includes: - Tooling evaluation table (Quartz, MkDocs, mdBook, Hugo, Docusaurus) - Requirements (Obsidian compatibility, wiki-links, HTML/PDF output) - Note on project naming (BlumeOps / blumeops / Blue Mops) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
fb8f98a47d
commit
38dae76cb9
1 changed files with 85 additions and 19 deletions
104
docs/README.md
104
docs/README.md
|
|
@ -1,52 +1,118 @@
|
|||
# Blumeops Documentation
|
||||
# BlumeOps Documentation
|
||||
|
||||
This directory contains documentation for blumeops, Erich Blume's personal infrastructure GitOps repository.
|
||||
> **Note on naming**: The project is properly stylized as **BlumeOps**, though "blumeops" and "Blue Mops" are also commonly used interchangeably.
|
||||
|
||||
This directory contains documentation for BlumeOps, Erich Blume's personal infrastructure GitOps repository.
|
||||
|
||||
## Documentation Restructuring (In Progress)
|
||||
|
||||
The documentation is being restructured to follow the [Diataxis](https://diataxis.fr/) documentation framework while serving multiple audiences:
|
||||
The documentation is being restructured to follow the [Diataxis](https://diataxis.fr/) documentation framework while serving multiple audiences.
|
||||
|
||||
### Target Audiences
|
||||
|
||||
1. **Erich (owner)** - A knowledge graph/zettelkasten for quickly recalling important facts about blumeops infrastructure and operations.
|
||||
1. **Erich (owner)** - A knowledge graph/zettelkasten for quickly recalling important facts about BlumeOps infrastructure and operations.
|
||||
|
||||
2. **Claude/AI agents** - Memory and context enrichment for AI-assisted operations and development.
|
||||
|
||||
3. **New external readers** - People who want to understand "what is blumeops?" at a high level.
|
||||
3. **New external readers** - People who want to understand "what is BlumeOps?" at a high level.
|
||||
|
||||
4. **Potential operators/contributors** - External readers who want to help operate, modify, or answer questions about blumeops, or onboard as a member.
|
||||
4. **Potential operators/contributors** - External readers who want to help operate, modify, or answer questions about BlumeOps, or onboard as a member.
|
||||
|
||||
5. **Replicators** - People who want to duplicate this approach for their own personal infrastructure operations.
|
||||
|
||||
### Planned Structure (Diataxis)
|
||||
### Requirements
|
||||
|
||||
The final documentation structure will include:
|
||||
- **Source format**: Markdown with optional YAML frontmatter
|
||||
- **Editing**: Compatible with [Obsidian](https://obsidian.md) and [obsidian.nvim](https://github.com/obsidian-nvim/obsidian.nvim)
|
||||
- **Cross-references**: Wiki-link syntax (`[[link]]`) for internal links
|
||||
- **Output formats**: HTML (for web hosting) and PDF (for offline reference)
|
||||
- **Changelog**: Track significant documentation changes
|
||||
|
||||
- **Tutorials** - Learning-oriented guides for getting started
|
||||
- **How-to Guides** - Task-oriented instructions for specific operations
|
||||
- **Reference** - Information-oriented technical descriptions
|
||||
- **Explanation** - Understanding-oriented discussion of concepts and decisions
|
||||
### Tooling Options (To Evaluate)
|
||||
|
||||
### Current State
|
||||
Several markdown-to-HTML/PDF tools to consider:
|
||||
|
||||
The restructuring is happening in phases:
|
||||
| Tool | Language | Obsidian Compatibility | Notes |
|
||||
|------|----------|------------------------|-------|
|
||||
| [Quartz](https://quartz.jzhao.xyz/) | TypeScript | Excellent (designed for Obsidian) | Wiki-links, backlinks, graph view |
|
||||
| [MkDocs](https://www.mkdocs.org/) + [Material](https://squidfunk.github.io/mkdocs-material/) | Python | Good (with plugins) | Very popular, great search |
|
||||
| [mdBook](https://rust-lang.github.io/mdBook/) | Rust | Limited | Simple, fast, used by Rust docs |
|
||||
| [Hugo](https://gohugo.io/) | Go | Moderate | Fast builds, flexible |
|
||||
| [Docusaurus](https://docusaurus.io/) | React | Limited | Feature-rich, heavier |
|
||||
|
||||
- **Phase 1** (current): Move existing zettelkasten cards to `docs/zk/` as a temporary holding area
|
||||
- **Future phases**: Build out the new Diataxis-based structure, migrate relevant content from zk cards, and eventually deprecate or integrate the zk format
|
||||
**Leaning toward**: Quartz (best Obsidian compatibility) or MkDocs Material (most mature ecosystem).
|
||||
|
||||
### Directory Layout
|
||||
## Restructuring Phases
|
||||
|
||||
### Phase 1: Foundation (Current)
|
||||
- [x] Move existing zk cards to `docs/zk/`
|
||||
- [x] Update `zk-docs` mise task for new path
|
||||
- [x] Create this README with restructuring plan
|
||||
- [ ] Evaluate and select documentation build tooling
|
||||
- [ ] Set up basic build pipeline (mise task or CI)
|
||||
- [ ] Create `CHANGELOG.md`
|
||||
|
||||
### Phase 2: Tutorials
|
||||
Learning-oriented content for getting started.
|
||||
|
||||
- [ ] Create `tutorials/` directory
|
||||
- [ ] "Getting Started with BlumeOps" - What this is and how to explore it
|
||||
- [ ] "Setting Up a Similar Environment" - For replicators
|
||||
- [ ] "Your First Contribution" - For potential contributors
|
||||
|
||||
### Phase 3: How-to Guides
|
||||
Task-oriented instructions for specific operations.
|
||||
|
||||
- [ ] Create `how-to/` directory
|
||||
- [ ] Migrate operational content from zk cards
|
||||
- [ ] "How to deploy a new Kubernetes service"
|
||||
- [ ] "How to add a new Ansible role"
|
||||
- [ ] "How to update Tailscale ACLs"
|
||||
- [ ] "How to troubleshoot common issues"
|
||||
|
||||
### Phase 4: Reference
|
||||
Information-oriented technical descriptions.
|
||||
|
||||
- [ ] Create `reference/` directory
|
||||
- [ ] Service reference pages (migrate from zk cards)
|
||||
- [ ] Infrastructure inventory
|
||||
- [ ] Configuration reference
|
||||
- [ ] API/CLI reference for mise tasks
|
||||
|
||||
### Phase 5: Explanation
|
||||
Understanding-oriented discussion of concepts and decisions.
|
||||
|
||||
- [ ] Create `explanation/` directory
|
||||
- [ ] "Why GitOps?" - Philosophy and approach
|
||||
- [ ] "Architecture Overview" - How everything fits together
|
||||
- [ ] "Security Model" - Tailscale, secrets management, etc.
|
||||
- [ ] "Decision Log" - ADRs (Architecture Decision Records)
|
||||
|
||||
### Phase 6: Integration & Cleanup
|
||||
- [ ] Migrate remaining useful content from `docs/zk/`
|
||||
- [ ] Decide fate of zk cards (archive, delete, or keep as separate knowledge base)
|
||||
- [ ] Update CLAUDE.md to reference new doc structure
|
||||
- [ ] Set up automated doc builds (CI/CD)
|
||||
- [ ] Consider hosting docs publicly (GitHub Pages, etc.)
|
||||
|
||||
## Current Directory Layout
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md # This file
|
||||
└── zk/ # Zettelkasten cards (temporary location during restructuring)
|
||||
├── CHANGELOG.md # Documentation changelog (planned)
|
||||
├── tutorials/ # Learning-oriented (planned)
|
||||
├── how-to/ # Task-oriented (planned)
|
||||
├── reference/ # Information-oriented (planned)
|
||||
├── explanation/ # Understanding-oriented (planned)
|
||||
└── zk/ # Zettelkasten cards (temporary)
|
||||
├── 1767747119-YCPO.md # Main blumeops overview card
|
||||
└── ... # Service-specific cards and notes
|
||||
```
|
||||
|
||||
## Viewing the ZK Cards
|
||||
|
||||
To view all blumeops zettelkasten cards:
|
||||
To view all BlumeOps zettelkasten cards:
|
||||
|
||||
```fish
|
||||
mise run zk-docs
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue