You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
Prerequisites → same developer guide, not the front page
Deploy on the cluster / Uninstall → docs/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.
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 ofmakeinvocations 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
docs/— one line per destination, no procedures inlineWhat should move to
docs/docs/development/running-locally.mddocs/deployment/(or fold into an existing operator-facing page)Also worth doing while in there
docs/has no index. Adddocs/README.mdgrouping the existing trees (api/,runbooks/,testing/,enhancements/,diagrams/) so the README can link to one place instead of eleven.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.