Tidy up docs structure

[sanity]

Near‑term structural tidy‑up

• Remove duplication in dev / developer-guide

  • Move everything under resources/manual/developer-guide into /dev (or vice‑versa).
  • Delete the duplicate section after the move.

• Adopt Diátaxis split

  • Under resources/manual create four top‑level buckets:
    get-started/, concepts/, how-to/, reference/.
  • Re‑file existing pages into the right bucket.

• Replace repeated blurbs with links

  • On the Platform page, trim the contract explanation to a short teaser and link to concepts/contracts.
  • Audit other pages for duplicated text and replace with a link to the canonical doc.

---

Longer‑term polish

• Set up component‑level reuse so shared snippets (install commands, etc.) come from a single Markdown partial.
• Add audience filters (user, operator, developer) so readers can toggle views in the sidebar.

[sanity]

Issue Priority Assessment

Generated: 2026-02-18T22:13:06.388918458+00:00
Issue hash: 310a3969

Value Assessment

Pulling the repo into view shows that the Hugo site keeps its developer-facing material in parallel locations: the old “dev” tree under hugo-site/content/dev houses pages like platform/index.md, which currently serves as the landing point for Platform Development and already overlaps with the broader narrative in hugo-site/content/resources/manual/introduction.md:1-10. Having two sets of pages that both explain what Freenet Core is and how to get involved makes it hard for contributors to know where to read canonical guidance, especially because the “manual” folder already contains structured dossiers on architecture, components, contract-interface, and other sweeping topics that would be more navigable once Diátaxis buckets exist. Every time a detail in the Platform Development page changes it now needs to be synchronized with whatever equivalent chunk lives in the manual, so users who follow one path or the other get slightly different experiences.

Adopting Diátaxis folders right under hugo-site/content/resources/manual would let this repository’s documentation match the structured intent of “get started, concepts, how-to, and reference” that modern readers expect. At the moment, the manual itself is a grab bag (architecture sections nested under architecture/, crypto-contract notes in contract-interface.md, tutorials in tutorial.md, etc.), but there are no obvious canonical buckets for workflows versus concepts. Moving everything under resources/manual/developer-guide into the /dev tree (or vice versa) and then filing those pages into the four Diátaxis buckets would give the site a single source of truth, reducing the chance that we tell developers to “see the Platform page” while operators are pointed to a differently written manual entry.

That tidy-up also unlocks the longer-term goals outlined in the issue: once content is consistently structured it becomes easier to replace repeated blocks of text (e.g., the contract explanation that is duplicated on the Platform page) with links to a single canonical doc, and to reuse shared snippets through Markdown partials instead of copying install instructions into every tutorial. Those foundational changes will prevent future contributors from having to chase down the right file to edit when an install command or glossary term needs updating, which in turn removes a latent blocking factor for doc contributions. Without the cleanup and the audience-filter work, developers, operators, and end users all spend more time hunting for the right explanation for their role.

There’s no pressing external deadline for these changes, so this isn’t an emergency, but the longer the overlap persists the more confusion it seeds in the documentation. Getting the restructure done before additional people start relying on the manual (or before new Diátaxis-style content is written) keeps future updates inexpensive, so I’d rank the issue as moderately urgent for maintaining documentation cohesion even if it isn’t a blocker for the rest of the codebase.

Cost Assessment

The manual is currently a single landing page that links to the components, architecture, developer guide, examples, community, and reference sections (see hugo-site/content/resources/manual/_index.md:13), and its content lives in roughly 17 Markdown files under hugo-site/content/resources/manual/ plus the nested components and architecture folders. The developer guide slice of that manual—tutorial, contract-interface, and manifest (hugo-site/content/resources/manual/tutorial.md:1, hugo-site/content/resources/manual/contract-interface.md:1, hugo-site/content/resources/manual/manifest.md:1)—overlaps conceptually with the /dev section that currently holds platform and apps (hugo-site/content/dev/platform/index.md:1, hugo-site/content/dev/apps/index.md:1). Moving these pages into a Diátaxis-structured hierarchy of get-started/, concepts/, how-to/, and reference/, and deleting their old copies means moving or copying every manual file into the appropriate bucket, updating front matter to match the new sections, and adjusting the /dev tree so it either references the relocated material or consumes it directly.

Beyond the physical moves, the site navigation and cross-links will need a comprehensive refresh: the menu blocks in hugo-site/hugo.toml:21 currently point to the resources/manual anchors and will need new targets for the Diátaxis folders, and dozens of pages reference the legacy URLs (hugo-site/content/quickstart/_index.md:85, hugo-site/content/faq/index.md:44, hugo-site/static/slides/common/call-to-action.html:20, CONTRIBUTING.md:37). The Platform page (and any other developer-facing pages) would have to trim repeated concept blurbs and convert them to links pointing to the forthcoming concepts/contracts page, which implies creating that page under the new structure and ensuring both dev and resources content point at the same canonical file instead of duplicating prose. “Component-level reuse” would then require adding a partial or shortcode (e.g., stored with the theme templates so snippets can be included via {{< snippet "install" >}}) and updating every current install/command block such as the curl installer in hugo-site/content/quickstart/_index.md:23 to call that snippet, which touches both theme code and every Markdown file that formerly repeated the same text.

Because so many pieces would be renamed and relocated, there is serious risk of broken external links and menu items; every reference in the repo to /resources/manual/... would need review, and the HTML menus that rely on those URLs (hugo-site/hugo.toml:21 again) must be kept in sync. Introducing audience filters would compound this risk, since the base single template offers no such interactivity today (hugo-site/themes/freenet/layouts/_default/single.html:1); adding toggles plus the supporting JS/CSS and front‐matter flags exposes the rendering layer to regressions, especially given how sparse the current layout is. Those audience toggles will need to be designed so they do not break existing content or cause SEO/Accessibility issues, and the new partial-driven snippets must be kept in sync with both the Diátaxis structure and the /dev pages.

Testing will be manual: after the reorganization you will need to run the documentation site via hugo server -D (or cargo make dev to cover the broader build) to confirm the new directories resolve, the navigation still renders, and no broken anchor links appear in the menu or in the quickstart/faq/slide references. The new snippet partials and audience toggles also need local verification by opening affected pages and exercising the UI controls, since there are no automated tests covering static content. Once the build succeeds, double-check that the slidedeck snippets and README references still resolve to the right paths.

Next steps: 1) map each existing manual page into the appropriate Diátaxis bucket and decide whether it stays under resources or migrates under /dev; 2) update hugo-site/hugo.toml, the Quickstart/FAQ/slides/CONTRIBUTING references, and any other hardcoded URLs before moving files; 3) prototype the shared-snippet partial plus the audience-filter UI so that docs authors can reuse commands and toggle views without duplicating text.

---

Generated by issue-prioritizer