documentation-docusaurus/references/research-led-evidence-registry-ia.md

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.