Docs IA v2 Audit
Audit of the previous documentation structure and the reasoning behind the audience-first redesign.
#Key findings
- Security and provenance topics were important but fragmented across overview and developer pages.
- Tokenomics lived outside the docs portal, which made it harder to discover in the main navigation.
- RFC-heavy material appeared too early for first-time readers.
- Merchant documentation had strong procedures, but weaker business-value framing and checklist discovery.
#As-Is map
- `lib/docs.ts` → `/docs`, `/docs/introduction`, `/docs/getting-started`, `/docs/rfc-index`, `/docs/governance-and-security-model`, `/docs/audit-and-provenance` — audience: mixed — quality: clarity 3/5, completeness 4/5, freshness 3/5.
- `lib/docs.ts` → `/docs/user-guide/*` — audience: user — quality: clarity 4/5, completeness 4/5, freshness 3/5.
- `lib/docs.ts` → `/docs/merchant-guide/*` — audience: merchant — quality: clarity 4/5, completeness 4/5, freshness 3/5.
- `lib/docs.ts` → `/docs/developer-guide/*` — audience: developer — quality: clarity 3/5, completeness 4/5, freshness 4/5.
- `app/litepaper/page.tsx`, `content/litepaper-tokenomics.md`, `content/tokenomics-faq.md`, `lib/tokenomics.ts` — audience: mixed/tokenomics — quality: clarity 3/5, completeness 4/5, freshness 4/5.
#Gaps and duplication
- Duplicate safety language existed across user transaction, payment, and security pages.
- Merchant payout and reconciliation guidance overlapped but did not lead with treasury-close language.
- Developer retry, policy, and event concepts were distributed across several pages instead of one onboarding path.
- Beginner explanations for tokenomics, governance, and confidentiality terms were too thin.
#Migration and redirect plan
- The new sidebar leads with Users, Merchants, Developers, Tokenomics, Security and Risk, and RFC / Technical Specs.
- Existing detailed routes stay live so current links continue to work.
- New overview pages link readers into existing deep pages instead of replacing them with less detailed copies.
- Release notes document the IA v2 rollout so external readers can understand the change.