Repository navigation
Documentation for go-live #89
Description
Activity
- added a commit that references this issue
on Aug 29, 2025 Went back and forth with @.claude a bunch about documentation best practices, and thinking through the different user journeys people will have with the registry. Came up with this plan together, which I think seems good and is what I will proceed with - feedback welcomed :)
Documentation plan
Documentation Restructure Analysis
Current State Analysis
Your current docs mix different purposes and audiences:
- Mixed content types: FAQ combines "what is" explanations with "how to" procedures
- Technical specs scattered: API docs in subdirs, but no clear learning path
- Developer vs. user content blended: Publisher README has both contributor and user info
- Deep technical details up front: server.json schema before basic concepts
Diataxis Framework Applied
Diataxis organizes docs into 4 quadrants based on practical/theoretical and learning/working:
Learning-oriented | Problem-oriented ─────────────────────┼───────────────────── Practical TUTORIALS | HOW-TO GUIDES ─────────────────────┼───────────────────── Theoretical EXPLANATIONS | REFERENCEProposed Restructure for Issue #89
Here's how I'd restructure to address the specific docs needed:
1. Entry Point (Progressive Disclosure)
docs/ ├── README.md # Hub with clear paths to each quadrant ├── tutorials/ # TUTORIALS (learning-oriented) ├── guides/ # HOW-TO (problem-oriented) ├── explanations/ # EXPLANATIONS (understanding-oriented) └── reference/ # REFERENCE (information-oriented)2. Tutorials
tutorials/ ├── README.md # "Choose your path" ├── publish-your-first-server.md # End-to-end walkthrough ├── understand-server-json.md # What is server.json + simple example └── setup-ci-publishing.md # CI integration tutorial3. How-To Guides
guides/ ├── publishing/ │ ├── write-basic-server.md # Building a minimal MCP server - maybe link to main MCP docs or link to example repos │ ├── write-server-json.md # How to write server.json │ ├── use-publisher-cli.md # CLI instructions │ ├── setup-ci-pipeline.md # CI integration with GitHub Actions (alt: maybe an auth/ subfolder for each method) │ └── manage-versions.md # Version management ├── consuming/ │ ├── build-etl-mirror.md # ETL mirror design │ ├── use-rest-api.md # REST API usage │ └── add-custom-annotations.md # Custom _meta annotations (alt: maybe this moves to explanations?) └── administration/ ├── moderation-guidelines.md └── admin-operations.md4. Explanations
explanations/ ├── registry-concepts.md # What is a registry, metaregistry concept ├── ecosystem-vision.md # How registries/subregistries work together ├── design-principles.md # Design principles for the registry ├── namespacing.md # How namespacing works, security model └── versioning.md # Why immutable versions, semver5. Reference
reference/ ├── api/ │ ├── generic-registry-api.md. # server-registry-api/openapi.yaml probably lives here │ └── official-registry-api.md # May just link to live openapi docs ├── server.json/ │ ├── generic-server-json.md │ └── official-registry-requirements.md ├── cli/ │ └── publisher-commands.md └── faq.md # Keep FAQ but focused on quick answersSpecific Solutions for Issue #89
For each requested doc:
1. "How to write a server.json" →
guides/publishing/write-server-json.md- Progressive disclosure: Start with minimal example, then show advanced features
- Link to full schema in reference section
- Include validation checklist
2. "Instructions for using the publish CLI" →
guides/publishing/use-publisher-cli.md- Task-oriented: Each authentication method as separate section
- Link to tutorial for first-time users
- Troubleshooting section at end
3. "ETL mirror and REST API usage" →
guides/consuming/build-etl-mirror.md+guides/consuming/use-rest-api.md- Practical examples with code snippets
- Rate limiting and caching strategies
- Architecture diagrams
4. "Version management FAQ" →
guides/publishing/manage-versions.md- Address remote server versioning specifically
- Decision tree for version strategies
- Link to conceptual explanation of why versions are immutable
5. "CI pipeline integration" →
guides/publishing/setup-ci-pipeline.md- Step-by-step for GitHub Actions, GitLab, etc.
- Token management best practices
- Example workflows
Progressive Disclosure in Action
Entry point (docs/README.md):
# MCP Registry Documentation ## I want to... - **📤 Publish my MCP server** → [Publishing Tutorial](tutorials/publish-your-first-server.md) - **📥 Consume registry data** → [API Usage Guide](guides/consuming/use-rest-api.md) - **🔧 Set up automated publishing** → [CI Integration Guide](guides/publishing/setup-ci-pipeline.md) - **❓ Understand the registry concepts** → [Registry Concepts](explanations/registry-concepts.md) - **📋 Look up specific information** → [API Reference](reference/api/) | [CLI Reference](reference/cli/)
Each guide starts with what you'll accomplish, prerequisites, then progressively reveals complexity.
This structure separates the different needs your users have - some want to understand concepts, others just want to accomplish a task, others need to look up specific details.
Reacted by Tadas Antanavicius+1 from my side, the doc plan looks really nice! 💯
Reacted by adam jones and Tadas Antanavicius- added a commit that references this issue
on Sep 12, 2025
We should draft these in this repository first, and then probably lift some references into the official docs just prior to go-live:
Misc. FAQ we should add:
version, esp. as a remote server (Shouldrepositorybe required on Servers? #111 (comment))