As a registry server user, I want complete and well-structured documentation, so that I can quickly learn to configure, publish to, and deploy the registry

[danbarr]

Overview

The initial Registry Server documentation (PR #348) is comprehensive and technically solid, but needs structural improvements and some missing content to provide a better user experience.

High Priority

1. Add publishing guidance (CRITICAL GAP)

Missing: How do users actually publish MCP servers into the registry?

• Document the file format for Git/local file sources
• Explain Git repository structure and requirements
• Document the /publish API endpoint with examples
• Show the difference between publishing to managed vs file-based registries

2. Create quickstart tutorial

Location: New page in tutorials section

• Get users running in 5 minutes with minimal config
• Use anonymous auth + local file source
• Include a simple example MCP server entry
• Link from intro as the "fast path to experimentation"

3. Fix user journey and navigation

Issue: "Next steps" sections are inconsistent and sometimes circular

• Establish canonical learning path: Intro → Configuration → Authentication → Database → Deployment
• Update all "Next steps" sections to support this progression
• Remove duplicate "Deploy" link in intro.mdx

Medium Priority

4. Resolve intro/index redundancy

Issue: index.mdx is just a landing page, intro.mdx has the actual content

• Consider merging into single entry page, OR
• Make index.mdx more substantive with clear value proposition

5. Expand or refocus deployment documentation

Issue: deployment.mdx is thin (169 lines) and scope is unclear

• Either focus solely on Kubernetes (update title/intro), OR
• Add Docker, local development, and production considerations
• Add a minimal example before the complex one
• Consider adding: scaling guidance, monitoring, upgrade procedures

6. Consider splitting authentication documentation

Issue: authentication.mdx is comprehensive but overwhelming (463 lines)

• Option 1: Split into "Authentication basics" and "Advanced authentication"
• Option 2: Use progressive disclosure with collapsible sections for provider examples
• Keep the excellent security best practices prominent

Low Priority

7. Improve terminology consistency

• Standardize: "ToolHive Registry Server" on first use, "Registry server" thereafter
• Define or replace "knowledge workers" (appears once without context)
• Consistent capitalization throughout

8. Add missing contextual information

• System requirements
• Link to API reference or OpenAPI documentation
• Monitoring and observability guidance
• Upgrade and migration procedures
• Relationship to ToolHive CLI

9. Minor style guide compliance

• Replace occasional "we recommend" with "you should" (second person voice)
• Ensure consistent voice throughout

Related

• PR Add ToolHive Registry documentation #348 (initial documentation)

[danbarr]

Checked the current state of the registry docs against the issues raised here. Several items have been addressed since this was filed; others remain open.

Addressed

#3 - User journey and navigation: The duplicate "Deploy" link in intro.mdx is gone. Navigation flows logically through the section.

#4 - Intro/index redundancy: index.mdx is now more substantive - it has an intro paragraph, a "Where to start" navigation guide, and a DocCardList. This is consistent with the pattern used in other sections.

#5 - Deployment documentation: deployment.mdx has been refactored into a clean overview page that links out to two detailed pages: deploy-operator.mdx and deploy-manual.mdx. The scope is clear (Kubernetes only).

#8 (partial) - Missing contextual information: The intro's "Next steps" now links to the API reference. A telemetry-metrics.mdx page has been added covering monitoring/observability.

#9 - Style guide compliance: No instances of "we recommend" remain in the registry docs. Voice is consistent throughout.

Partially addressed

#1 - Publishing guidance: The managed registry section in configuration.mdx documents the /publish and DELETE endpoints, and skills.mdx covers the full skills publishing lifecycle via the API. However, the original gap is still largely open:

• No documentation of the JSON file format that Git and local file sources expect
• No Git repository structure guidance (layout, required fields, branch/tag conventions)
• No worked example of publishing an MCP server via the /publish endpoint

#7 - Terminology consistency: First-use capitalization ("ToolHive Registry Server") is consistent. However, "knowledge workers" (intro.mdx, line 100) still appears once without definition or context.

Still open

#2 - Quickstart: No quickstart exists for the Registry Server. The tutorials/custom-registry.mdx page is about the built-in registry, not the Registry Server. This remains the most impactful missing piece for new users.

#6 - Split authentication docs: authentication.mdx has grown from 463 to 552 lines. No structural changes have been made to address the overwhelming length.

#8 (remaining gaps): System requirements, upgrade/migration procedures, and the relationship between the Registry Server and ToolHive CLI are still not documented.