planet/docs/documentation-coverage-rules.md

Documentation Coverage Rules

This file contains Planet-specific documentation coverage rules. Documentation skills and agents should read this file before deciding which docs to update. Keep tool-specific workflow in skills; keep product and repository rules here.

Audience Routing (mandatory)

Before deciding scope, classify the change by who performs the action:

• Browser/UI end user (login, account settings, configuring collectors or AI via UI, using Earth/Console pages): update docs/technical/{zh,en}/manual.md and quickstart.md only. Never put shell commands, log file paths, planet.sh, Docker operations, or netsh portproxy rules into these files.
• Operations / deployment / on-call (planet.sh, log paths, SMTP fallbacks like createuser, LAN/portproxy, env-var tuning, troubleshooting order, Bun build conventions): update docs/technical/{zh,en}/ops-runbook.md (or an existing ops-*.md). Never put UI button labels or screenshots into these files.
• Second-party developers (component context, render order, internal pipelines): update the existing *-context.md / backend-*.md / earth-*.md files.

If the same action has both a UI and a CLI path (e.g. user creation), describe the UI path in manual.md and the CLI path in ops-runbook.md, and cross-link them with a single sentence each.

Scope Rules

• Focus documentation changes on the primary document that owns the affected behavior. Do not trigger speculative updates across secondary or architectural docs unless the underlying contract or operator-facing workflow actually changed.
• User-visible workflow changes must update docs/technical/zh/manual.md and usually docs/technical/zh/quickstart.md.
• If an English counterpart exists for user-facing docs such as manual.md or quickstart.md, update docs/technical/en/... enough that it does not contradict the Chinese source.
• Control console page responsibility changes must update docs/technical/zh/frontend-admin-frontend-context.md.
• Earth frontend behavior changes must update docs/technical/zh/earth-frontend-context.md.
• Earth layer additions, renderOrder, altitude/radius offsets, depth strategy, pointer picking, legend modes, or layer panel/startup ordering must update docs/technical/zh/earth-render-layer-order.md.
• Earth layer visual style or legend symbol/color semantics should also update docs/technical/zh/earth-layer-style-reference.md when that reference is affected.
• Collector, datasource, credential, settings, connectivity, scheduler, or API changes must update the relevant backend docs, especially docs/technical/zh/backend-collectors.md and any datasource/settings-specific doc.
• When a change turns an old plan assumption into current behavior, update the relevant docs/plans/*.md with a status note instead of leaving contradictory instructions.
• Search docs for stale terms introduced by the change, for example old tab names, old route responsibilities, obsolete auth assumptions, or renamed UI labels.
• Internal bug fixes or optimizations that preserve existing APIs and workflows do not require updating user manuals or creating new documentation.

Public Docs Rules

• If adding a new technical document, add it to docs/technical/zh/README.md when it should be discoverable from the technical docs index.
• If a technical document should be visible in the public Docs page or linked from a technical README, register it in frontend/src/pages/Docs/docs-content.ts under DOCS_METADATA. Files under docs/technical/{zh,en}/ are not automatically routable.
• For every public technical doc, keep the bilingual file pair in sync by filename: docs/technical/zh/<name>.md and docs/technical/en/<name>.md. If content is intentionally Chinese-only or English-only, state that intentionally in the final note.
• Public docs should use readable link text, not raw filenames such as manual.md.

Credential Collector Rules

• Any built-in collector marked requires_credentials: true and credential_status: supported must have:
  • a credential_provider in backend/app/core/datasource_defaults.py;
  • a default credential guide in backend/app/services/credential_guides.py;
  • a supported connectivity provider in backend/app/services/datasource_connectivity.py;
  • settings UI guidance or a credential form in frontend/src/admin/pages/PlainResourcePages.tsx;
  • a regression test that fails if the guide/provider is missing.

Recommended Checks

Always run the centralized harness documentation gate:

scripts/harness/docs-consistency-check.sh

This single command automatically covers:

1. Public docs whitelist and DOCS_METADATA synchronization (frontend/src/pages/Docs/docs-content.ts vs backend Gatekeeper)
2. Technical doc bilingual file pairs and identical duplicate-content detection
3. Public doc link validity and human-readable link titles (no raw .md filenames)
4. Language-scoped internal links (docs/technical/zh/ links pointing to docs/technical/zh/)
5. Supported credential collector contracts and UI guide registration
6. Manual console route coverage against actual admin manifests
7. Documented ?section= deep-link validity and UI route drift in active docs