Skip to content

Information Architecture#

ErgoDocs has grown from topic pages, ecosystem notes, tutorials, protocol references, and generated API material. That growth is useful, but the repository now needs clearer ownership boundaries so navigation does not become the content model.

Target Model#

Use one canonical home for each page. Other sections should link to that page through curated hub pages, not duplicate the same file in multiple top-level nav surfaces.

Surface Job Canonical content
Start Here orientation and first decisions short routing pages that point to canonical hubs
Use user jobs and practical tasks wallets, safety, wallet guides, user tutorials
Ecosystem project discovery and ecosystem categories dApps, bridges, DeFi, NFTs, privacy tools, project profiles
Learn concepts and research protocol concepts, papers, cryptography, scaling
Mine network security and mining tasks miner setup, pools, rewards, and mining governance
Participate community and contribution governance, events, docs process, funding
Develop builder references SDKs, ErgoScript, data model, APIs, examples
Deploy operator runbooks node, indexers, watchers, pools, infrastructure
Reference lookup material glossary, FAQ, API references, standards, configuration references

Current Structural Risks#

Run these commands for current counts and structural findings:

.venv/bin/python tools/nav_audit.py --strict
.venv/bin/python tools/structure_audit.py --strict
.venv/bin/python tools/structure_audit.py --markdown

The audit tracks active docs, nav entries, duplicate targets, cross-surface duplicates, orphans, maximum nav depth, and source-watch coverage by content area.

Check for these structural risks as documentation is added:

  • A page may acquire several top-level nav locations. Keep one canonical location, and link from other hubs.
  • Project pages, conceptual pages, and operational runbooks are mixed in the same folders, especially under eco/, uses/, and dev/stack/; nav placement should be based on audience and content type, not path alone.
  • Some pages exist as navigation bridges rather than canonical references, making source ownership and update responsibility less clear.

The Starter Tutorial and Learning Resources belong under Develop → Start Here. Keep language-specific choices under SDKs, Frameworks & Tools, and use Technical Lookup for reference discovery.

Rules#

  • A page should have one canonical nav location.
  • A page can appear in another journey only through a hub page with a short summary and link.
  • Start Here is a routing layer. Keep it shallow and point to hubs, not deep technical pages.
  • Use pages should explain user outcomes and risks, not implementation details.
  • Ecosystem pages should support discovery of active, emerging, historical, or research-stage projects.
  • Develop pages should document APIs, libraries, contracts, and source-backed behavior.
  • Deploy pages should be runbooks: prerequisites, config, operations, failure modes, upgrades.
  • Learn pages should be stable conceptual references and should not depend on live project status.
  • Reference pages should be lookup material, not learning paths or tutorials.
  • Ecosystem project pages should declare status: active, dormant, prototype, historical, or unknown.
  • Source-backed pages should carry owner, last_reviewed, and source_repos frontmatter.
  • Replaced, alias, draft, or directory-listed pages should declare ia_status: legacy, ia_status: alias, ia_status: draft, or ia_status: directory instead of silently becoming orphan debt.
  • Use ia_status: directory only when an active page is intentionally discoverable through a directory or hub page instead of the sidebar.

Migration Plan#

  1. Pick canonical homes for cross-surface duplicates. Inventory existing explanations, examples, diagrams, and references first; navigation maintenance must preserve them.
  2. Replace duplicate nav entries with hub links.
  3. Split mixed pages when they combine concept, runbook, and project status.
  4. Move dormant or historical ecosystem pages into a clearly labelled archive path only after redirects exist. Preserve heading anchors when changing page structure.
  5. Add source-watch metadata to pages that describe changing APIs, contracts, configs, or active repositories.
  6. Keep generated API docs separate from authored API guidance.

High-Value Restructure Candidates#

  • Rosen watcher docs: canonical home is now Deploy / Rosen Bridge; Use / Rosen Bridge keeps user-facing Rosen concepts and no longer duplicates watcher runbooks.
  • Blockchain indexing docs: canonical home is now Deploy / Blockchain Indexing; Develop keeps API and explorer references without duplicating indexing runbooks.
  • Mosaik and legacy frameworks: split active SDK guidance from historical examples.
  • Ecosystem directory: continue adding status taxonomy; navigation now separates ecosystem/project pages from user tasks, operator runbooks, and developer references.
  • Node docs: keep generated OpenAPI under node/swagger/; keep authored guidance in node/swagger.md and dev/integration/.
  • Remaining work should focus on page quality inside overlarge buckets, especially Ecosystem / Applications & Utilities, Develop / Tooling & Frameworks, and node operations.

After navigation or link changes, build the site and run tools/internal_link_audit.py --site-dir <build-directory> --strict to check rendered links, cards, images, and fragments. Structural checks do not validate technical explanations or code examples.

Review Checklist#

  • Does this page have one canonical audience?
  • Is this page in only one top-level nav surface?
  • Does changing source code or config affect this page?
  • Is project status explicit?
  • Could this page be a hub link instead of a duplicated nav target?
  • Would a new contributor know who owns updates?