From a606cea5a1d0bc88ec1e5c52d535a9cc559c9e79 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Tue, 3 Feb 2026 13:01:22 -0800 Subject: [PATCH] Reorder docs phases: Reference before Tutorials (#87) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Move Reference from Phase 4 to Phase 2 in the documentation restructuring plan - Update directory layout in README to reflect new phase order - Add explanatory note about why Reference comes first (so other docs can link to it) ## Deployment and Testing - [x] Updated docs/README.md with new phase order - [x] Added towncrier changelog fragment - [ ] Ready to proceed with Phase 2 (Reference) content after merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/87 --- docs/README.md | 32 ++++++++++--------- .../changelog.d/docs-phase-2-reference.doc.md | 1 + 2 files changed, 18 insertions(+), 15 deletions(-) create mode 100644 docs/changelog.d/docs-phase-2-reference.doc.md diff --git a/docs/README.md b/docs/README.md index 76a2d19..4403aea 100644 --- a/docs/README.md +++ b/docs/README.md @@ -64,7 +64,16 @@ The documentation is being restructured to follow the [Diataxis](https://diataxi **Docs URL:** https://docs.ops.eblu.me -### Phase 2: Tutorials +### Phase 2: Reference +Information-oriented technical descriptions. Built first so other docs can link to reference material. + +- [ ] Create `reference/` directory +- [ ] Service reference pages (migrate from zk cards) +- [ ] Infrastructure inventory +- [ ] Configuration reference +- [ ] API/CLI reference for mise tasks + +### Phase 3: Tutorials Learning-oriented content for getting started. - [ ] Create `tutorials/` directory @@ -72,7 +81,7 @@ Learning-oriented content for getting started. - [ ] "Setting Up a Similar Environment" - For replicators - [ ] "Your First Contribution" - For potential contributors -### Phase 3: How-to Guides +### Phase 4: How-to Guides Task-oriented instructions for specific operations. - [ ] Create `how-to/` directory @@ -82,15 +91,6 @@ Task-oriented instructions for specific operations. - [ ] "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. @@ -113,15 +113,17 @@ docs/ ├── README.md # This file ├── CHANGELOG.md # Release changelog (built by towncrier) ├── changelog.d/ # Towncrier news fragments -├── tutorials/ # Learning-oriented (planned) -├── how-to/ # Task-oriented (planned) -├── reference/ # Information-oriented (planned) -├── explanation/ # Understanding-oriented (planned) +├── reference/ # Information-oriented (Phase 2) +├── tutorials/ # Learning-oriented (Phase 3) +├── how-to/ # Task-oriented (Phase 4) +├── explanation/ # Understanding-oriented (Phase 5) └── zk/ # Zettelkasten cards (temporary) ├── 1767747119-YCPO.md # Main blumeops overview card └── ... # Service-specific cards and notes ``` +> **Why Reference first?** Reference docs are built before tutorials and how-to guides so that learning and task-oriented content can link to authoritative technical descriptions using wiki-links (`[[reference/service-name]]`). + ## Adding Changelog Entries When making changes, add a news fragment to `docs/changelog.d/`: diff --git a/docs/changelog.d/docs-phase-2-reference.doc.md b/docs/changelog.d/docs-phase-2-reference.doc.md new file mode 100644 index 0000000..bdf94d9 --- /dev/null +++ b/docs/changelog.d/docs-phase-2-reference.doc.md @@ -0,0 +1 @@ +Reorder documentation phases: Reference (Phase 2) now comes before Tutorials (Phase 3) so other docs can link to reference material