feat: merge Docusaurus and Gitea documentation skills

2026-08-14 12:32:08 +00:00
parent cfb006d7ea
commit b08614dc90
28 changed files with 4202 additions and 1 deletions
@@ -0,0 +1,59 @@
+# Research-led information architecture for evidence registries
+
+Use this pattern when a Docusaurus site publishes a large evidence corpus organized around entities (for example clients) and derived records (for example systems).
+
+## Guidance synthesis
+
+Authoritative sources:
+
+- GOV.UK content planning: begin with user needs and choose formats around tasks rather than mirroring the publisher's organization.
+- GOV.UK writing guidance: use clear titles, summaries, headings, language, and descriptive links so users can find and understand content.
+- W3C WAI design guidance: preserve clear hierarchy, meaningful controls, keyboard-visible focus, and multiple understandable ways to locate information.
+- USWDS card guidance: cards should be coherent entry points within a collection, each covering one subject and leading to detail.
+- USWDS table guidance: tables suit long, structured, comparable registries when headers and interpretation are explicit.
+
+## Recommended portal model
+
+1. Identify the dominant user tasks before editing navigation. For an entity/evidence registry these are usually:
+   - find an entity;
+   - follow a system/topic across entities;
+   - search names, aliases, contractors, and evidence text;
+   - understand methodology;
+   - verify or reuse source data.
+2. Make the first three tasks the homepage's equal primary discovery paths. Keep methodology and provenance globally available but visually secondary.
+3. Use stable global navigation labels based on destinations, such as `Overview`, `Clients`, `Systems`, `Methodology`, and `Data`. Avoid mixing a generated dossier sidebar destination with a duplicate directory destination in the same global navigation.
+4. Keep large dossier sidebars available inside their docs plugin, but link global navigation to the registry/index page rather than opening an arbitrary first dossier.
+5. Present scope before detail and label each metric precisely: authoritative entities, consolidated records, and preserved evidence observations are different measures.
+6. Generate every changing count and overview table from canonical source data. Do not duplicate live totals in hand-maintained Markdown or JSX.
+7. Explain table ordering, status vocabulary, count semantics, and safe interpretation immediately before long registry tables.
+8. State explicitly that an association may mean ownership, use, procurement, operation, hosting, maintenance, support, or another relationship. Counts summarize public evidence, not a complete inventory.
+9. Preserve direct provenance at detail level: every derived record must link observations back to canonical dossiers and evidence.
+10. Record the reviewed guidance and resulting IA decisions in a repository research note so future redesigns can distinguish intentional structure from accidental layout.
+
+## Docusaurus implementation notes
+
+- Ensure both the top-level `title` and visible navbar title use the requested product name; changing only `themeConfig.navbar.title` leaves page titles inconsistent.
+- For task-oriented global navigation, direct `to:` links to registry/index routes are often clearer than `docSidebar` items that enter a very large sidebar at its first document.
+- Keep the navbar persistent when users frequently move among large registries.
+- A homepage search card/button should focus the theme-owned navbar search input or dispatch its shortcut; never mount a second search component.
+- Give button-based cards the same geometry, typography, hover state, and `:focus-visible` treatment as link cards.
+- Use semantic `nav`, `section`, `aside`, headings, real links, and real buttons.
+- Preserve square geometry when required by the site's design language.
+
+## Verification
+
+1. Regenerate source-derived content before validation.
+2. Run repository validation, TypeScript checking, production build, and `git diff --check`.
+3. Verify representative entity, derived-record, methodology, provenance, and search-index routes.
+4. Inspect the homepage visually for hierarchy, alignment, clipping, overlap, and consistency.
+5. Exercise the search trigger in a browser and inspect console/JavaScript errors.
+6. Commit and push only after local checks pass; observe the exact Gitea Actions run through success.
+7. Verify distinctive changed text through the deployed backend or an authorized browser. If public Pages is intentionally OAuth-protected, treat the expected redirect separately from backend deployment health.
+
+## Pitfalls
+
+- Do not present entity count, unique-record count, and observation count as interchangeable.
+- Do not make four or five homepage cards compete equally when only three are primary discovery tasks.
+- Do not hard-code generated overview/status counts in Markdown.
+- Do not infer that a successful Actions run alone proves the served content changed; verify a distinctive marker.
+- Do not diagnose an OAuth redirect as a Docusaurus deployment failure.