Skip to content

Documentation Quality Plan.md

Latest commit

 

History

History
128 lines (95 loc) · 5.07 KB

Documentation Quality Plan.md

File metadata and controls

128 lines (95 loc) · 5.07 KB
Raw

Documentation Quality Plan

This plan keeps the README, wiki, media, and release documentation useful as the MCP ecosystem changes.

Documentation Goals

The docs should let a new operator:

  1. Understand the project value in the first README screen.
  2. Choose stdio, Streamable HTTP, or OpenAPI without guessing.
  3. Install in a common MCP client in a few minutes.
  4. Verify success with read-only tools before mutating Proxmox.
  5. Understand the security model before exposing the server.
  6. Find the right tool for a VM, LXC, snapshot, backup, ISO, command, or job workflow.
  7. Debug common startup, auth, TLS, SSH, and health-check problems.

README Standard

The README should stay optimized for GitHub scanning:

  • one-sentence positioning statement
  • badges for package, release, CI, container, and license
  • architecture image near the top
  • three quick-start paths: MCP stdio, MCP Streamable HTTP, OpenAPI
  • one-click install buttons where supported
  • short demo section with GIF and MP4 link
  • tool-selection table for common workflows
  • compact safety model
  • clear links into the wiki for long-form details

Avoid moving full reference material into the README. Keep reference detail in wiki pages or generated docs.

Wiki Standard

The wiki should be task-oriented:

Page Purpose
Home routing page and five-minute path
Client Setup client-specific install and verification
Operator Guide runtime modes, config, deployment, health, logs
Tool Selection Guide goal-to-tool workflow guidance
Security Guide auth, TLS, command policy, approval, exposure controls
Container Command Execution SSH-backed LXC command setup
API & Tool Reference exact tools, inputs, prerequisites, failures
Troubleshooting symptom-driven fixes
Developer Guide local dev, tests, release workflow
Release & Upgrade Notes compatibility and upgrade impact

Media Plan

Keep existing assets:

  • docs/assets/logo-proxmoxmcp-plus.png
  • docs/assets/logo-proxmoxmcp-plus-400.png
  • docs/assets/proxmoxmcp-drawio-hero-main-refresh.svg
  • docs/assets/proxmoxmcp-demo.gif
  • docs/assets/proxmoxmcp-demo.mp4

Recommended new assets when real screenshots or recordings are available:

Asset Purpose
docs/assets/client-connected-vscode.png prove the MCP server is visible in a mainstream IDE
docs/assets/client-connected-cursor.png show client install success for Cursor users
docs/assets/job-lifecycle.png explain natural language request -> MCP tool -> Proxmox UPID -> job_id
docs/assets/security-flow.png show Proxmox token, OpenAPI bearer auth, TLS, command policy, and Host/Origin checks
YouTube or release-asset demo video 60-90 second live workflow from install to read-only verification to one controlled mutation

Do not add placeholder screenshots. Only publish assets captured from a working client or lab.

Docs Site Plan

The repository can continue publishing docs/wiki/ to GitHub Wiki. A future docs site should use the repository as the source of truth and publish to GitHub Pages.

Recommended path:

  1. Add a lightweight static docs generator such as MkDocs Material.
  2. Treat docs/wiki/ as the initial content source.
  3. Publish on tags and on main.
  4. Generate llms.txt and llms-full.txt during the docs build.
  5. Keep GitHub Wiki pages as a mirror for users who prefer the GitHub UI.

LLM Documentation Entry Points

Maintain a small docs/llms.txt index for AI clients. It should link to:

  • README
  • Client Setup
  • Operator Guide
  • Tool Selection Guide
  • Security Guide
  • API & Tool Reference
  • Troubleshooting
  • Release & Upgrade Notes

If a full docs export is added later, keep it generated rather than hand-maintained.

Automation Checklist

Add or keep checks that prevent documentation drift:

  • markdown formatting check for README and docs
  • link check for relative links
  • JSON validation for config examples and MCP client snippets where possible
  • manifest/runtime parity test for tool registration
  • generated API/tool reference from runtime tool metadata or manifest.json
  • asset existence check for README images and video links
  • release checklist entry requiring README/wiki updates for user-facing changes

Release Documentation Checklist

For each release that changes behavior:

  1. Update README.md only if the first-run path, capability list, safety model, or install path changed.
  2. Update docs/wiki/API & Tool Reference.md for tool names, inputs, prerequisites, and failure modes.
  3. Update docs/wiki/Operator Guide.md for config, runtime, Docker, health, or logging changes.
  4. Update docs/wiki/Security Guide.md for auth, TLS, command policy, or exposure changes.
  5. Update docs/wiki/Release & Upgrade Notes.md with upgrade and rollback guidance.
  6. Update server.json and manifest.json if package metadata or environment variables changed.
  7. Run the docs validation checklist before publishing.

Related Pages