Skip to content

docs: restructure docs/ to be service-centric with README linking out to guides #321

Description

@ecv

Summary

The README has become the catch-all for anything a reader might need — product overview, prerequisites, local development loop, deploy/uninstall instructions — while docs/ holds the actual reference material (API pages, runbooks, enhancements, testing guides) that nothing links to. A contributor landing on the repo reads a wall of make invocations before learning what the service does, and an operator looking for a runbook has no path to it from the front page.

Restructure so the README is service/product-centric and links out to task-specific guides under docs/.

What the README should be

  • What Datum Network Services is, and the boundary with infrastructure providers (already there — keep it)
  • The resource model at a glance: Networks, Network Contexts, Subnets, HTTPProxies, Domains, TrafficProtectionPolicies
  • A short "where to go next" index into docs/ — one line per destination, no procedures inline

What should move to docs/

  • Running locally for development (added in docs: add running the operator locally guide #310) → docs/development/running-locally.md
  • Prerequisites → same developer guide, not the front page
  • Deploy on the cluster / Uninstalldocs/deployment/ (or fold into an existing operator-facing page)

Also worth doing while in there

  • docs/ has no index. Add docs/README.md grouping the existing trees (api/, runbooks/, testing/, enhancements/, diagrams/) so the README can link to one place instead of eleven.
  • The README's Documentation section still says docs.datum.net is coming "shortly." Either point at what exists today or drop it until the site is live.

Scope note

Docs-only reorganization — no content rewrites beyond what relocation requires. Keep each fact owned once: if a page moves, leave a link, not a copy.

Raised by @scotwells in review of #310.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Fields

Priority

None yet

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions