Info-arch restructure

[johnnymatthews]

The docs have evolved significantly since this project started. Instead of a products-based approach (Indexer, Hosts, Views, etc) we need to move to a hybrid persona + Diátaxis model.

How we're gonna do it

Basically, adopt a hybrid structure. Goal-based tracks at the top level, Diátaxis modes (tutorial / how-to / reference / explanation) used to organise content within each track.

Rejected alternatives and why

Before we get into the meat of this task, here's other stuff we considered but abandoned:

Pure persona

This fights over cross-cutting content. One topic needed by several audiences forces duplication or a junk-drawer owner.

Pure Diátaxis

Scatters each role's content across all four sections; bad when operators and developers are genuinely different humans.

Pure topic/domain

Reproduces the ownership fights one level down.

Lifecycle/journey spine

Developer and operator journeys diverge too hard for one linear spine.

Proposed tree

Home
│
├── Understand                          (evaluator front door + shared concepts)
│   ├── What is Shinzo                  [explanation]
│   ├── How it works                    [explanation]
│   ├── Core concepts                   [explanation]
│   │   ├── Views
│   │   ├── Attestation
│   │   ├── DefraDB
│   │   └── SHNZ token / economics
│   └── ELI5 Architecture               [explanation]
│
├── Build apps                          (developer / View creator)
│   ├── Your first app                  [tutorial]
│   ├── Create a View                   [how-to]
│   ├── Build an app                    [how-to]
│   ├── Query data                      [how-to]
│   ├── Publish & earn                  [how-to]
│   └── Concepts (builder-framed)       [explanation]
│       ├── Views for builders
│       ├── Economics of views/requests
│       └── Attestation as a query filter
│
├── Run infrastructure                  (indexer + host operator)
│   ├── Get started                     [tutorial]
│   ├── Run an Indexer                  [how-to]
│   │   ├── Install (Docker / source)
│   │   └── Register
│   ├── Run a Host                      [how-to]
│   │   ├── Install (Docker / source)
│   │   └── Configure event filters
│   ├── Operations                      [how-to]
│   │   ├── Key & identity management
│   │   ├── Backups
│   │   ├── Monitoring
│   │   └── Troubleshooting
│   ├── Private Hosts                   [how-to]
│   └── Earnings                        [explanation]
│
└── Reference                           (role-agnostic, all lookup)
    ├── Architecture (deep)             [reference]
    ├── Components                      [reference]
    │   ├── Indexer client
    │   ├── Host client
    │   ├── ShinzoHub
    │   ├── SourceHub
    │   ├── Outpost
    │   ├── viewkit
    │   ├── DefraDB
    │   └── Lens (LensVM)
    ├── Data model                      [reference]
    │   ├── Primitives
    │   ├── Signatures
    │   ├── AttestationRecord
    │   ├── Naming convention
    │   ├── DefraDB metadata
    │   └── Schema directives
    ├── GraphQL API                     [reference]
    └── Specs & limits                  [reference]

Key structural decisions

• We've gone with goal labels over identity labels (Understand / Build / Run, not "For developers / For researchers"), because one person wears several hats in a session.
• Revenue is not a top-level section. It's an outcome of two roles, so it threads in as Publish & earn (Build) and Earnings (Run infra), with shared economics living in Core concepts.
• Reference is centralised, not mirrored. All lookup-shaped, role-agnostic content pools in one track; the Build/Run tracks cross-link into it rather than duplicating. Reference is the most cross-cutting type you have, so centralising it is the whole point.
• Shared explanations live in the Understand section. Core concepts (Views, Attestation, DefraDB, SHNZ) has one canonical home; everything else cross-links to it.
• Architecture is deliberately written twice. There's a gentle explanation in Understand for evaluators, and then we go deep (two-chains/IBC/ICA spec) in Reference for implementers. This is the one intentional duplication.
• FAQ are gone. Stuff like "Does it replace my node" is all merged into explanations. "How do I back up keys" is now in how-to (Operations). "RPC methods / storage / sync" is all in Reference.

Gaps to fill

There are obviously some pages that need writing. Completing these pages does not fall under this IA task, but I've put them here for future reference anyway:

• Private host connections. #243
• Key / asset management. #244
• Earnings / economics. #245

[soniasingla]

@johnnymatthews thanks for putting this together, a couple of long-term concerns:

• Reference is likely to grow much faster than the other sections. Centralizing it is the right call, but we may eventually need a dedicated IA within Reference to keep it manageable.
• The other thing is Diátaxis drift. The structure is clean now, but over time people naturally start mixing explanations, how-tos, tutorials, and reference content into the same pages. That’s probably the main thing I’d watch out for as the docs grow.

[johnnymatthews]

Reference is likely to grow

Agreed. We can expand on the Reference section once it gets big enough. I don't mind changing sub-sections (like everything under /reference), but I'd like to not touch top-level sections if we can.

but over time people naturally start mixing explanations, how-tos, tutorials, and reference content into the same pages

Yeah that's a fair point, and not something that I'd considered. I guess we can try and be proactive in corralling contributions into the correct spots.