Skip to content

Documentation Quality Plan

RekklesNA edited this page Sep 4, 2026 · 1 revision

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

Clone this wiki locally