Skip to content

[Enhancement]: Audit guides-k8s Prerequisites sections for repeated boilerplate #1015

Description

@danbarr

Page or section

docs/toolhive/guides-k8s/ - Prerequisites sections across multiple how-to guides.

What could be better?

While restructuring the K8s auth docs (#1014), we trimmed the Prerequisites sections on auth-k8s.mdx, embedded-auth-server-k8s.mdx, authorization-k8s.mdx, and token-exchange-k8s.mdx down to what's actually specific to each page, dropping boilerplate like "Kubernetes cluster with RBAC enabled," "ToolHive Operator installed," and "kubectl access to your cluster." These are how-to guides, not tutorials - by the time a reader reaches any page in this section, they've already been through Introduction/Quickstart/Deploy the Operator and that baseline no longer needs restating on every subsequent page.

That same boilerplate still exists elsewhere in guides-k8s/:

  • run-mcp-k8s.mdx lists "A Kubernetes cluster," "Permissions to create resources," "kubectl configured," and "The ToolHive operator installed" - though as one of the first how-to pages in the section, some of this may be more justified here than on deeper pages.
  • connect-clients.mdx repeats "kubectl configured to communicate with your cluster."

Two pages already show the tighter pattern worth generalizing: rate-limiting.mdx and redis-session-storage.mdx condense this down to a single "Kubernetes cluster with the ToolHive Operator installed" bullet (or drop it entirely), keeping only what's genuinely specific to that page.

Proposed improvement

Audit every guides-k8s/ how-to's Prerequisites section and remove restated cluster/kubectl/operator boilerplate, keeping only page-specific requirements - following the pattern already used in rate-limiting.mdx and redis-session-storage.mdx, and the fix applied to the four auth pages in #1014.

Additional context

Scoped to guides-k8s/ since that's where this was found, but worth a quick check of whether the same pattern shows up in guides-cli/, guides-vmcp/, or guides-registry/ too - a first pass didn't turn up much there, but it wasn't an exhaustive check.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or requestneeds-triageIssue needs initial triage by a maintainer

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions