docs: builder docs information architecture redesign

[BrianSeong99]

Builder Docs Information Architecture

Design Principle

Every page answers ONE question type. The type determines the section.

Developer asks	Section
"Set me up"	Get Started
"How do I build contracts?"	Smart Contracts (concepts + API)
"What tools are available?"	Tools (reference + guides, grouped by workflow)
"Walk me through building X"	Tutorials (multi-part guided learning)
"How do I upgrade?"	Migration

Sections link to each other, never duplicate content.

---

Final Structure

docs/builder/
│
├── get-started/                             ① Onboarding (renamed from quick-start/)
│   ├── setup/
│   │   ├── installation.md                  midenup install
│   │   └── cli-basics.md                    first commands
│   └── your-first-smart-contract/
│       ├── create.md
│       ├── deploy.md
│       └── test.md
│
├── smart-contracts/                         ② Concepts + API (local only, no ingested content)
│   ├── overview.md
│   ├── getting-started.md                   toolchain & project structure
│   ├── accounts/
│   │   └── ...existing concept pages...
│   ├── notes/
│   │   └── ...existing concept pages...
│   ├── transactions/
│   │   └── ...existing concept pages...
│   ├── api-reference.md
│   ├── types.md
│   ├── cross-component-calls.md
│   └── patterns.md
│
├── tools/                                   ③ Reference + Guides (by workflow)
│   ├── index.md                             overview of all tools
│   ├── development/
│   │   ├── midenup.md
│   │   ├── miden-cli.md
│   │   ├── cargo-miden.md
│   │   └── templates.md                     rust, frontend, masm
│   ├── testing/                             local — moved from develop/tutorials/rust-compiler/
│   │   ├── mockchain.md                     (from testing.md)
│   │   ├── debugging.md                     (from debugging.md)
│   │   └── pitfalls.md                      (from pitfalls.md)
│   ├── clients/                             ingested from miden-client repo
│   │   ├── rust-client/
│   │   └── web-client/
│   └── infrastructure/
│       ├── node-setup.md
│       ├── playground.md
│       └── explorer.md
│
├── tutorials/                               ④ Entire miden-tutorials repo ingested here
│   ├── index.md                             (ingested)
│   ├── rust-client/                         (ingested)
│   ├── web-client/                          (ingested)
│   └── miden-bank/                          (moved to tutorials repo, ingested back)
│       ├── index.md
│       ├── 00-project-setup.md
│       ├── ...
│       └── 08-complete-flows.md
│
├── migration/                               ⑤
├── faq.md
└── glossary.md

---

What Changes vs Today

Today	After	Why
quick-start/	get-started/	Standard naming
smart-contracts/ (mixed concepts + ref)	smart-contracts/ (concepts + API only)	Clean separation — examples live in tutorials/
develop/tutorials/ (ingested + local mixed)	tutorials/ (all ingested from one repo)	Single source of truth, clean ingestion
tools/ is 1-page stub	tools/ comprehensive, grouped by workflow	Every tool gets a page
Guides in develop/tutorials/rust-compiler/	tools/testing/ (local)	Testing/debugging are tool-oriented, not tutorials
develop/index.md stale version note	Deleted	Content is in proper sections now

---

Cross-Linking Strategy

Smart contract concept pages cross-link to relevant tutorials rather than embedding examples:

smart-contracts/accounts/overview.md
  → "See tutorials for hands-on examples:"
  → links to tutorials/rust-client/counter_contract_tutorial
  → links to tutorials/web-client/counter_contract_tutorial

smart-contracts/notes/overview.md
  → links to tutorials/rust-client/mint_consume_create_tutorial
  → links to tutorials/rust-client/custom_note_how_to

tutorials/miden-bank/00-project-setup.md
  → links to tools/development/cargo-miden
  → links to smart-contracts/getting-started

tools/testing/mockchain.md
  → links to tutorials/miden-bank (examples in context)

---

Content Ownership

Section	Owner	Source
get-started/	miden-docs	Local
smart-contracts/	miden-docs	Local
tools/development/	miden-docs	Local (cargo-miden possibly ingested from compiler repo)
tools/testing/	miden-docs	Local (moved from develop/tutorials/rust-compiler/)
tools/clients/	miden-client repo	CI ingests
tools/infrastructure/	miden-docs	Local
tutorials/	miden-tutorials repo	CI ingests entire repo
migration/	miden-docs	Local

---

CI Pipeline Changes

Current (deploy-docs.yml lines 180-184, cut-versions.yml lines 184-188)

if [ -d "vendor/miden-tutorials/docs/src" ]; then
  mkdir -p docs/builder/develop/tutorials
  cp -r vendor/miden-tutorials/docs/src/* docs/builder/develop/tutorials/
  echo "Synced miden-tutorials → docs/builder/develop/tutorials"
fi

After

if [ -d "vendor/miden-tutorials/docs/src" ]; then
  mkdir -p docs/builder/tutorials
  cp -r vendor/miden-tutorials/docs/src/* docs/builder/tutorials/
  echo "Synced miden-tutorials → docs/builder/tutorials"
fi

That's it — one path change. No multi-target copies, no merging.

Note: The preservation comment on lines 151/155 about "NOT fully cleaned to preserve local tutorials" is no longer needed — tutorials/ will be fully ingested content, and local guides move to tools/testing/.

---

Implementation Phases

Phase 1: Content moves within miden-docs

1. Rename quick-start/ → get-started/
2. Move develop/tutorials/rust-compiler/{testing,debugging,pitfalls}.md → tools/testing/
3. Delete develop/ directory (all content relocated)
4. Update cross-reference links

Phase 2: Move miden-bank to tutorials repo

1. Move develop/tutorials/rust-compiler/miden-bank/ → miden-tutorials repo (tutorials#165)
2. Remove local miden-bank from miden-docs

Phase 3: Update CI

1. Change ingestion path in deploy-docs.yml (lines 180-184)
2. Change ingestion path in cut-versions.yml (lines 184-188)
3. Remove preservation comments (lines 151/155 in both files)
4. Update verification output paths

Phase 4: Cross-linking

1. Add "See tutorials" links from smart-contracts concept pages to tutorials/
2. Add "See concepts" links from tutorials back to smart-contracts/
3. Verify all internal links resolve

---

Files to Update

CI pipeline files

• .github/workflows/deploy-docs.yml (lines 151, 180-184, 198-199)
• .github/workflows/cut-versions.yml (lines 155, 184-188, 202-203)

Cross-reference files (add tutorial links)

• docs/builder/smart-contracts/index.md
• docs/builder/smart-contracts/overview.md
• docs/builder/smart-contracts/getting-started.md
• docs/builder/smart-contracts/patterns.md

Local files to move

• docs/builder/develop/tutorials/rust-compiler/testing.md → docs/builder/tools/testing/mockchain.md
• docs/builder/develop/tutorials/rust-compiler/debugging.md → docs/builder/tools/testing/debugging.md
• docs/builder/develop/tutorials/rust-compiler/pitfalls.md → docs/builder/tools/testing/pitfalls.md

Local files to move to tutorials repo

• docs/builder/develop/tutorials/rust-compiler/miden-bank/* (11 files — see tutorials#165)

---

Tutorial Gaps Identified

Gap	Description	Priority
Deploy to Testnet	Miden-bank only uses MockChain; no on-chain deployment tutorial	High
Custom Notes	Standalone tutorial for note types beyond P2ID (swap, escrow, time-locked)	Medium
Oracle Pattern	Existed in v0.12 legacy tutorials, absent from new structure	Medium
Client Integration	Guide for using miden-client for account management & transaction submission	High

[BrianSeong99]

Update: Partial implementation landed in #188

PR #188 implements a subset of this plan. Here's the current state:

Done (PR #188)

• Flattened develop/: docs/builder/develop/tutorials/ → docs/builder/tutorials/
• CI pipeline updated: Both deploy-docs.yml and cut-versions.yml now ingest into docs/builder/tutorials/
• Sidebar section headers: Builder sidebar now uses manual config with non-clickable section headers (Getting Started, Build, Solutions, Reference)
• Private Multisig flattened: Appears directly under Solutions section, no redundant wrapper category
• All internal links fixed: Across both docs/ and versioned_docs/version-0.13/
• Legacy redirect added: Old builder/develop/tutorials URLs redirect properly

Updated structure (current)

docs/builder/
├── quick-start/              ① Onboarding (not yet renamed to get-started/)
├── smart-contracts/          ② Concepts + API
├── tutorials/                ③ Moved up from develop/tutorials/ ✅
├── tools/                    ④ Reference + Guides
├── miden-guardian/           ⑤ Guardian docs
├── solutions/
│   └── private-multisig/     ⑥ Shown directly in Solutions sidebar section
├── migration/
├── faq.md
└── glossary.md

Remaining phases

• Phase 1 (partial): Rename quick-start/ → get-started/, move testing guides to tools/testing/
• Phase 2: Move miden-bank to tutorials repo (see tutorials#165)
• Phase 4: Cross-linking between smart-contracts and tutorials

[Keinberger]

Hey Brian, thanks for the work on #188, the manual sidebar and section headers are nice!!

I'll go ahead with the quick-start => get-started rename (you already proposed it here). Before proceeding with the rest, I'd like your input on one structural addition:

Adding a Guides section

I think we should add a Guides category to the sidebar (between Tutorials and Tools):

• Tutorials = "follow me from start to finish" (Miden Bank, future apps)
• Guides = "how do I do X right now?" (testing, debugging, pitfalls, FPI)

Aptos, Sui, and Starknet all separate these. The existing testing/debugging/pitfalls files are workflow guides, not tutorials, and they'd be the first items in this section.

The Guides section would also house the existing MASM tutorials under a "MASM (Advanced)" subsection, keeping them accessible for advanced users without confusing beginners on the default Rust compiler path.

The sidebar would look something like:

Build
  Smart Contracts [...]
  Tutorials
    Miden Bank [Parts 0-8]
  Guides                          ← NEW
    Testing with MockChain
    Debugging Guide
    Common Pitfalls
    Node Setup
    MASM (Advanced)
      Rust Client [12 tutorials]
      Web Client [6 tutorials]
  Tools
    Client [ingested]

How the CI ingestion would change

For context, docs/builder/ has content from three sources:

• Locally authored (in miden-docs): smart-contracts, get-started, miden-guardian, private-multisig, faq, glossary, etc.
• Ingested from miden-tutorials: currently lands in tutorials/
• Ingested from miden-client: lands in tools/client/

The miden-client ingestion stays exactly the same (full clean + cp -r into tools/client/). The only change is how miden-tutorials content gets mapped.

Right now both deploy-docs.yml and cut-versions.yml do a single flat copy:

cp -r vendor/miden-tutorials/docs/src/* docs/builder/tutorials/

This works because miden-tutorials has a flat docs/src/ and everything lands in tutorials/. But it also means we need the preservation comment ("NOT fully cleaned to preserve local tutorials") since miden-bank lives locally in tutorials/rust-compiler/.

With the restructured miden-tutorials repo (see my comment on tutorials#165), the single cp -r becomes targeted copies:

# Tutorial content (miden-bank, future families)
cp vendor/miden-tutorials/docs/src/index.md docs/builder/tutorials/
cp -r vendor/miden-tutorials/docs/src/miden-bank/ docs/builder/tutorials/miden-bank/

# Guides (testing, debugging, pitfalls, node-setup)
cp -r vendor/miden-tutorials/docs/src/guides/* docs/builder/guides/

# MASM tutorials under guides
cp -r vendor/miden-tutorials/docs/src/masm/* docs/builder/guides/masm/

The clean step also gets simpler. Instead of the preservation comment, we can just clean the ingested directories directly:

rm -rf docs/builder/tutorials/miden-bank docs/builder/tutorials/index.md
rm -rf docs/builder/guides

This removes the ambiguity of "which content is local vs ingested" since tutorials/rust-compiler/ gets deleted entirely (all that content now lives in miden-tutorials and gets ingested to the right places). Both workflows (deploy-docs.yml and cut-versions.yml) get the same change.

Does this work for you?

[BrianSeong99]

like this update a lot, Although I would try to categorize and organize the guides a little bit, right now they are a bit discrete and lack ordering and relationship between the guides. Maybe we should do this in another issue. But overall it makes a ton of sense

[Keinberger]

Hey Brian, glad you like it! Should I go ahead and implement the base structure (Guides section, moving the testing/debugging/pitfalls files, MASM subsection), or would you prefer to sync on the guide ordering first before I make the PR? Happy to discuss structure over Slack like usual and then capture the final layout in a dedicated issue.

Thanks!