Skip to content

Usability and navigation audit — 2026-04-18

Purpose: Document reader-facing friction in a large markdown wiki: flat catalogs, weak visual hierarchy, canonical vs supporting confusion, and source-note usability. This audit complements Structural debt audit — wiki IA and operational maturity (tooling/metadata) and Structural audit — page ownership, entity gaps, and hub routing (ownership). Companion pattern: Source-note abstract and evidence pattern.

Executive summary

Finding Severity Mitigation (this pass)
index.md Overview mixes onboarding, audits, package hubs, standards, procedural strategy, and many source-note previews—similar visual weight for different jobs High Tighten Overview: three reader lanes + pointer to hubs; move long source-note batch lines out of Overview where possible; link this audit + pattern page
Business plan section in index.md is a full TOC—correct for completeness, easy to mistake for “read all of this in order” Medium Emphasize Start here and package hub first; hubs already state canonical first; overview.md shortened to lane-based entry
Analyses section at bottom of index.md duplicates many links already reachable via hubs—escape hatch exists (Wiki navigation and structural hubs) but is not always obvious from the homepage Medium Surface themed entry in Overview + start-here table row; hub page unchanged in scope, clearer cross-links
Source-notes vary: some have purpose + synthesis hooks; others are path lists only—hard to scan in MkDocs or Obsidian Medium Standardized Evidence summary block on high-value cluster notes
Callouts and maturity: standards use page_subtype: standard; guides use operational_maturity—not all reader landing pages restate draft vs field_tested Low Audit only; defer bulk frontmatter edits unless a page is already being touched
Known / assumptions / unknowns: strongest on business plan and site intelligence pages; weaker on some topic hubs that are mostly link lists Medium Hubs retain tables; add one-line routing intent at top (targeted edits, not new pages)

A. Navigation audit

Flat or noisy index sections

  • index.md — Overview (~lines 4–51): Combines start pages, multiple structural audits, package hubs, operational standards (long bullet list), procedural guides, then additional links (structural debt, execution evidence cluster, inbox batches). Readers see ten-plus peer bullets before the Business plan heading.
  • index.md — Source notes (~lines 224–463): A single flat list of hundreds of entries—necessary for validator/orphan hygiene, but not a reading order. Discovery relies on cluster indexes and topic hubs.

Hubs that are strong vs weak

Hard to find from homepage / overview

  • Themed analyses entry: buried at bottom of index.md (## Analyses)—easy to miss when Overview is already long.
  • Evidence / provenance vocabulary: Evidence grade and canonical authority is linked from Start here but not from every hub; acceptable if Start here + overview stay prominent.

Where readers cannot tell where to start

  • Multiple structural audits in Overview (repository, ownership, entity gaps, source authority, structural debt)—all legitimate but overwhelming for a first visit. Mitigation: overview.md lanes + one link to this audit instead of repeating the full audit menu.

B. Style and structure audit

Weak summaries

  • Some topic pages are link-only after one paragraph; acceptable for hubs if the first screen states who should open this and what not to duplicate.
  • index.md Business plan and Analyses sections: by design comprehensive; risk is accidental linear reading. Mitigation: canonical-first language in package hub + execution dossier pointers.

Inconsistent callouts

  • Mix of **bold** purpose lines, tables, and horizontal rules—acceptable; avoid adding new ad-hoc emoji or HTML in markdown.

Tables and checklists

  • Hubs increasingly use tables (good). Standards use checklist-shaped prose—consistent with page_subtype: standard.

Status / maturity indicators

  • Operational pages: prefer operational_maturity where procedures exist (Procedural guides package strategy). Gap: not every hub repeats pilot vs production; low priority unless editing those pages for other reasons.

Known / assumptions / unknowns structure

C. Source-note improvement strategy (reference)

Implemented as a reusable block documented on Source-note abstract and evidence pattern. Principles:

  • Public-safe: Abstract and key claims must read clearly when raw/ links are neutralized in MkDocs (claims cite authority type, not only file paths).
  • Lightweight: one summary table or short sections—not a second full essay.
  • Canonical-first: every cluster note should link synthesis pages above the raw inventory.

D. Implemented routing updates (this session)

E. Deferred / next passes

  • Optional: split index.md Source notes into cluster indexes only in the Overview (would require policy change and validator alignment)—not done here.
  • Bulk operational_maturity on all runbooks—defer to procedural package owner.
  • MkDocs theme tweaks (fonts, sidebar)—out of scope for markdown-only pass.

See also