From e5cc00f1ccdc13e2c52d75e1f58c5346e11384b8 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Thu, 5 Feb 2026 12:53:44 -0800 Subject: [PATCH] Review exploring-the-docs: fix links, add Related section Co-Authored-By: Claude Opus 4.6 --- .../doc-exploring-the-docs-review.doc.md | 1 + docs/tutorials/exploring-the-docs.md | 27 +++++++++++-------- 2 files changed, 17 insertions(+), 11 deletions(-) create mode 100644 docs/changelog.d/doc-exploring-the-docs-review.doc.md diff --git a/docs/changelog.d/doc-exploring-the-docs-review.doc.md b/docs/changelog.d/doc-exploring-the-docs-review.doc.md new file mode 100644 index 0000000..94241c9 --- /dev/null +++ b/docs/changelog.d/doc-exploring-the-docs-review.doc.md @@ -0,0 +1 @@ +Review and clean up exploring-the-docs tutorial: simplify wiki-links, fix broken replication/ reference, add Related section, match zk-docs flags to CLAUDE.md. diff --git a/docs/tutorials/exploring-the-docs.md b/docs/tutorials/exploring-the-docs.md index 8cf09e1..3ea01de 100644 --- a/docs/tutorials/exploring-the-docs.md +++ b/docs/tutorials/exploring-the-docs.md @@ -27,8 +27,8 @@ The docs follow the [Diataxis](https://diataxis.fr/) framework: ### For Erich (Owner) You probably want quick access to operational details: -- [[how-to|How-to guides]] for common operations (deploy, troubleshoot, update ACLs) -- [[reference|Reference]] has service URLs, commands, and config locations +- [[how-to]] guides for common operations (deploy, troubleshoot, update ACLs) +- [[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 @@ -36,30 +36,29 @@ You probably want quick access to operational details: Context for effective assistance: - Read [[ai-assistance-guide]] for operational conventions -- [[reference|Reference]] has the technical specifics you'll need +- [[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|Explanation]] covers the "why" behind design decisions -- [[reference|Reference]] shows what's actually running +- [[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|How-to guides]] for specific tasks (deploy services, add roles) -- [[reference|Reference]] tells you where things live +- [[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 -- [[explanation|Explanation]] covers architecture and design rationale -- The `replication/` tutorials go deep on components +- [[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 @@ -77,7 +76,13 @@ Pre-commit hooks automatically validate that all wiki-links point to existing fi The `zk-docs` mise task concatenates key documentation files for AI context: ```bash -mise run zk-docs +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 + +- [[tutorials]] - Parent index of all tutorials +- [[update-documentation]] - How to publish doc changes +- [[review-documentation]] - Periodic doc review process