From 8550cb9ecc4c3eaf5e90a797a2b3938d4caa6b66 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 27 Mar 2026 12:34:51 -0400 Subject: [PATCH 1/2] Update guidance files to reflect docs restructuring Update AGENTS.md/CLAUDE.md, STYLE-GUIDE.md, and skills (docs-review, upstream-release-docs) to encode the information architecture, design principles, and page conventions established during the Phase 1-3 docs restructuring. This ensures future contributions follow the new product-area-based structure. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/docs-review/SKILL.md | 14 ++++ .claude/skills/upstream-release-docs/SKILL.md | 13 +++- AGENTS.md | 78 +++++++++++++++---- STYLE-GUIDE.md | 38 +++++++++ 4 files changed, 124 insertions(+), 19 deletions(-) diff --git a/.claude/skills/docs-review/SKILL.md b/.claude/skills/docs-review/SKILL.md index c4fe7a8f..12089a2d 100644 --- a/.claude/skills/docs-review/SKILL.md +++ b/.claude/skills/docs-review/SKILL.md @@ -63,6 +63,18 @@ Watch for these telltale signs of AI-generated docs that need human intervention | Over-explaining | Verbose descriptions of obvious things | Trust the reader; cut aggressively | | Hedging language | "may," "might," "could potentially" | Be direct or remove | +### Section Structure and Navigation + +The docs follow a product-area-based information architecture. Check: + +- **Self-contained sections**: Product-specific content belongs in its product section (`guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`), not in a shared section. +- **Quickstarts in product sections**: Quickstarts live inside their product section, not in a separate top-level section. +- **Integration placement**: Third-party integration guides (ngrok, Vault, OpenTelemetry, Okta, etc.) belong in `integrations/`, not in a product section. +- **Next steps section**: Every how-to guide and tutorial page must end with a "Next steps" section containing 1-3 forward links. Missing "Next steps" is a primary issue. +- **Introduction pages**: Each product section should have an Introduction as the first sidebar child. New sections must follow this pattern. +- **Progressive disclosure**: Core workflows should appear before advanced topics. Check that advanced content isn't mixed in with beginner-facing pages. +- **Forward navigation path**: A reader should be able to follow "Next steps" links from the quickstart through core workflows without relying on the sidebar. + ### Clarity and Readability - **Passive voice**: "Backend discovery occurs" → "vMCP discovers backends" @@ -113,6 +125,8 @@ Structure your review as: **Primary issues** (address before merge): - Information architecture: content in wrong document, cross-document duplication +- Content placed in the wrong section (e.g., product-specific content in Concepts, integration content in a product section) +- Missing "Next steps" section on how-to guides and tutorials - Structure problems that harm navigation - Missing explanations for confusing design decisions - Significantly buried or redundant content diff --git a/.claude/skills/upstream-release-docs/SKILL.md b/.claude/skills/upstream-release-docs/SKILL.md index 22871017..d74e9fc7 100644 --- a/.claude/skills/upstream-release-docs/SKILL.md +++ b/.claude/skills/upstream-release-docs/SKILL.md @@ -124,6 +124,14 @@ Apply the approved changes: 2. **Create new pages** for new features that lack existing documentation. Default to documenting new features rather than skipping them: + **Page placement** — the docs are organized by product area. Place new content in the correct section: + - **Product-specific guides** go in the relevant product section (`guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`). + - **Third-party integration guides** go in `integrations/`. + - **Cross-cutting concepts** go in `concepts/`. + - **Per-MCP-server usage guides** go in `guides-mcp/`. + - **Reference material** goes in `reference/`. + - Check the project's CLAUDE.md "Information architecture" section for the full placement rules. + **Diataxis separation** — create separate pages per document type, not one combined page: - **Concept page** (explanation): What is this feature, why does it exist, when would you use it? Lead with concrete scenarios and user personas ("If you maintain a shared MCP registry and want to let teams publish reusable tool bundles..."). Explain relationships to existing features. - **Guide page** (how-to): Task-oriented, organized by user goals — not by API endpoint order. Include practical examples: realistic `curl` commands, sample payloads with plausible values, expected responses, and error cases. If a feature has both producer and consumer sides, document both workflows. @@ -145,9 +153,10 @@ Apply the approved changes: **Naming conventions** — when the feature introduces naming rules (e.g., kebab-case identifiers, camelCase config keys), call these out explicitly with examples of valid and invalid names. **Page mechanics:** - - Place each page in the appropriate directory - - Update sidebar/navigation configuration + - Place each page in the appropriate product section directory (see "Page placement" above) + - Update sidebar/navigation configuration in `sidebars.ts` - Update frontmatter descriptions on all new and modified pages + - Add a "Next steps" section at the end of every how-to guide and tutorial page with 1-3 forward links - Only skip creating a page that would duplicate auto-generated reference content (e.g., don't manually list API endpoints that are already in a swagger-rendered page) 3. **Add cross-references** — link new content from related existing pages and vice versa. diff --git a/AGENTS.md b/AGENTS.md index e47f8bff..6ec7a8e3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,23 +80,67 @@ The documentation should be accessible to a wide range of technical users, inclu ## Information architecture -This project follows the [Diataxis framework](https://diataxis.fr/) for documentation organization. Diataxis divides documentation into four types based on user needs: - -1. **Tutorials** (`/docs/toolhive/tutorials/`) - Learning-oriented, step-by-step lessons that guide users through completing a project or learning a concept. -2. **How-to guides** (`/docs/toolhive/guides-*/`) - Task-oriented, practical guides that show how to solve specific problems or accomplish specific tasks. -3. **Reference** (`/docs/toolhive/reference/`) - Information-oriented, technical descriptions of the machinery and how to operate it (API docs, CLI commands, configuration options). -4. **Explanation/Concepts** (`/docs/toolhive/concepts/`) - Understanding-oriented, explanations that clarify and illuminate topics, provide background and context. - -### When to create new pages - -Create a new documentation page when: - -- The content addresses a distinct task, concept, or reference topic that doesn't fit within existing pages. -- An existing page would become too long or cover too many disparate topics. -- The information architecture requires it (e.g., a new MCP server guide, a new tutorial). -- The content belongs to a different Diataxis category than existing content. - -Always consider where the new page fits in the Diataxis framework and place it in the appropriate directory. Update `/sidebars.ts` to include the new page in the navigation. +The docs are organized by **product area**, with each section self-contained so a reader can complete their journey without leaving it. Cross-cutting content lives in dedicated shared sections. The authoritative restructuring plan is in `/docs-restructuring/1-docs-restructuring-plan.md`. + +### Design principles + +1. **Route readers to value fast.** The home page helps a reader figure out where to go within 10 seconds. +2. **Each section is self-contained.** A reader in the CLI section shouldn't need to leave it to complete their task. Quickstarts, guides, and relevant reference material live together. +3. **Forward momentum on every page.** Every page ends with a "Next steps" section linking to the next logical page. +4. **Consistent structure across sections.** Each product area follows the same pattern: Introduction, Quickstart, how-to guides. +5. **Progressive disclosure.** Core workflows first, advanced topics grouped separately. + +### Top-level sections + +| Section | Folder | What belongs here | +| --- | --- | --- | +| ToolHive UI | `guides-ui/` | Desktop app guides, quickstart, and reference | +| ToolHive CLI | `guides-cli/` | CLI guides, quickstart, command reference, API reference | +| Kubernetes Operator | `guides-k8s/` | K8s deployment, operation, auth, telemetry, CRD reference | +| Virtual MCP Server | `guides-vmcp/` | Gateway/aggregation guides, quickstart, optimizer | +| Registry Server | `guides-registry/` | Registry Server deployment, config, auth, API reference | +| Integrations | `integrations/` | Cross-cutting third-party integration guides (ngrok, Vault, OpenTelemetry, Okta, etc.) | +| Concepts | `concepts/` | Cross-cutting explanations (MCP primer, groups, auth framework, observability, etc.) | +| MCP server guides | `guides-mcp/` | Per-server usage guides (auto-generated index) | +| Reference | `reference/` | Client compatibility, CLI commands, API specs, CRD specs, registry schemas | +| Tutorials | `tutorials/` | End-to-end tutorials that span multiple components (kept small; most tutorials moved to product sections or Integrations) | + +### Section skeleton + +Each product section follows this pattern: + +```text +[Product Area] (category label) +├── Introduction (what it is, who it's for, where to start) +├── Quickstart (hands-on in <10 minutes) +├── [How-to guides] (organized by journey phase) +│ ├── Install / Deploy +│ ├── Use +│ ├── Secure +│ ├── Operate +│ └── Optimize +└── [Reference] (inline where relevant) +``` + +Not every section needs every phase. The Introduction is an explicit first sidebar child, not a hidden category-link page. + +### Where to place new content + +- **Product-specific content** goes in the relevant product section (`guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`). +- **Quickstarts** live inside their product section, not in a separate top-level section. +- **Third-party integration guides** (connecting ToolHive with external tools/services) go in `integrations/`. +- **Cross-cutting concepts** (applicable to multiple product areas) go in `concepts/`. +- **Per-MCP-server usage guides** go in `guides-mcp/`. +- **Reference material** (specs, schemas, compatibility matrices) goes in `reference/`, with cross-links from the relevant product section. +- Update `/sidebars.ts` to include any new page in the navigation. + +### Page requirements + +Every how-to guide and tutorial page must include: + +- Front matter with `title` and `description`. +- A "Next steps" section at the end with 1-3 links to the next logical pages, following the journey phases (install, use, secure, operate, optimize). +- Cross-links to related content in other sections where relevant. ## Review process diff --git a/STYLE-GUIDE.md b/STYLE-GUIDE.md index c6e6da0f..3d4dc251 100644 --- a/STYLE-GUIDE.md +++ b/STYLE-GUIDE.md @@ -155,6 +155,44 @@ Considerations for screenshots and other images: - Use the primary brand colors (`#2D684B` on light backgrounds, `#BDDFC2` on dark backgrounds) for annotations like callouts and highlight boxes. +## Page structure + +Every how-to guide and tutorial page follows a consistent structure. This +ensures readers always know what to expect and never hit dead ends. + +### Front matter + +Every page must have front matter with at least a `title` and `description`. + +### Next steps + +Every how-to guide and tutorial page ends with a `## Next steps` section +containing 1-3 links to the next logical pages. These follow the journey phases: +install, use, secure, operate, optimize. Example: + +```mdx +## Next steps + +- [Run MCP servers](./run-mcp-servers.mdx) to deploy your first server. +- [Client configuration](./client-configuration.mdx) to connect your IDE. +``` + +### Introduction pages + +Each product section (UI, CLI, K8s, vMCP, Registry Server) has an Introduction +page as its first sidebar child. This page explains what the component is, who +it's for, and where to start. It is an explicit child item in the sidebar - not +a hidden category-link page. + +### Cross-references + +Link to related content in other sections where it adds value. Key patterns: + +- Product section auth pages link to the Concepts auth framework page. +- Product section telemetry pages link to the Integrations OpenTelemetry guide. +- The Registry Server introduction disambiguates from the built-in registry. +- The UI "Access the CLI" page links to the CLI section. + ## Markdown style Just like a consistent writing style is critical to clarity and messaging, From bf2f44476aa7c06d021bd9a6f152473a79fdfb4d Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 27 Mar 2026 12:42:04 -0400 Subject: [PATCH 2/2] Address review feedback: restore Diataxis, fix paths - Restore Diataxis framework reference as the underlying authoring model (it still applies, just not to folder structure) - Remove reference to transient restructuring plan document - Add docs/toolhive/ base path to all folder references so contributors place files correctly Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/docs-review/SKILL.md | 4 ++-- .claude/skills/upstream-release-docs/SKILL.md | 12 ++++++------ AGENTS.md | 4 +++- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/.claude/skills/docs-review/SKILL.md b/.claude/skills/docs-review/SKILL.md index 12089a2d..6fec7972 100644 --- a/.claude/skills/docs-review/SKILL.md +++ b/.claude/skills/docs-review/SKILL.md @@ -65,9 +65,9 @@ Watch for these telltale signs of AI-generated docs that need human intervention ### Section Structure and Navigation -The docs follow a product-area-based information architecture. Check: +The docs follow a product-area-based information architecture under `docs/toolhive/`. Check: -- **Self-contained sections**: Product-specific content belongs in its product section (`guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`), not in a shared section. +- **Self-contained sections**: Product-specific content belongs in its product section (`docs/toolhive/guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`), not in a shared section. - **Quickstarts in product sections**: Quickstarts live inside their product section, not in a separate top-level section. - **Integration placement**: Third-party integration guides (ngrok, Vault, OpenTelemetry, Okta, etc.) belong in `integrations/`, not in a product section. - **Next steps section**: Every how-to guide and tutorial page must end with a "Next steps" section containing 1-3 forward links. Missing "Next steps" is a primary issue. diff --git a/.claude/skills/upstream-release-docs/SKILL.md b/.claude/skills/upstream-release-docs/SKILL.md index d74e9fc7..73ffcfdc 100644 --- a/.claude/skills/upstream-release-docs/SKILL.md +++ b/.claude/skills/upstream-release-docs/SKILL.md @@ -124,12 +124,12 @@ Apply the approved changes: 2. **Create new pages** for new features that lack existing documentation. Default to documenting new features rather than skipping them: - **Page placement** — the docs are organized by product area. Place new content in the correct section: - - **Product-specific guides** go in the relevant product section (`guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`). - - **Third-party integration guides** go in `integrations/`. - - **Cross-cutting concepts** go in `concepts/`. - - **Per-MCP-server usage guides** go in `guides-mcp/`. - - **Reference material** goes in `reference/`. + **Page placement** — the docs are organized by product area under `docs/toolhive/`. Place new content in the correct section: + - **Product-specific guides** go in the relevant product section (`docs/toolhive/guides-ui/`, `guides-cli/`, `guides-k8s/`, `guides-vmcp/`, `guides-registry/`). + - **Third-party integration guides** go in `docs/toolhive/integrations/`. + - **Cross-cutting concepts** go in `docs/toolhive/concepts/`. + - **Per-MCP-server usage guides** go in `docs/toolhive/guides-mcp/`. + - **Reference material** goes in `docs/toolhive/reference/`. - Check the project's CLAUDE.md "Information architecture" section for the full placement rules. **Diataxis separation** — create separate pages per document type, not one combined page: diff --git a/AGENTS.md b/AGENTS.md index 6ec7a8e3..a5c45d78 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,7 +80,9 @@ The documentation should be accessible to a wide range of technical users, inclu ## Information architecture -The docs are organized by **product area**, with each section self-contained so a reader can complete their journey without leaving it. Cross-cutting content lives in dedicated shared sections. The authoritative restructuring plan is in `/docs-restructuring/1-docs-restructuring-plan.md`. +This project follows the [Diataxis framework](https://diataxis.fr/) for documentation authoring - each page is a tutorial, how-to guide, reference, or explanation. The site is organized by **product area**, with each section self-contained so a reader can complete their journey without leaving it. Cross-cutting content lives in dedicated shared sections. + +All documentation lives under `docs/toolhive/`. Folder paths below are relative to that root. ### Design principles