60 lines
4.8 KiB
Markdown
60 lines
4.8 KiB
Markdown
# 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.
|