diff --git a/.claude/skills/docs-review/SKILL.md b/.claude/skills/docs-review/SKILL.md index c4fe7a8f..6fec7972 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 under `docs/toolhive/`. Check: + +- **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. +- **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..73ffcfdc 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 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: - **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..a5c45d78 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,23 +80,69 @@ 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. +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 + +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,