0xMiden / 0xMiden/docs

Restructure tutorials section sidebar for clarity

Đang mở
#305 1 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
TypeScript
Star
10
Fork
50
Merge trung bình
22 ngày 23 giờ
Pull request đã merge (30 ngày)
1

Mô tả

## Summary

This issue proposes a tutorials section restructure to close the Quick Start to Miden Bank funnel, make MASM visible by name in the sidebar, and resolve a handful of label inconsistencies.

## Background

The current Tutorials section deploys as:

```
Tutorials
├── Miden Bank (10 parts, Rust compiler walkthrough)
├── Recipes
│ ├── Rust (12 pages)
│ └── Web / TypeScript (8 pages)
├── Development helpers (3 pages: testing, debugging, pitfalls)
└── Miden Node Setup (single leaf)
```

Three problems with this:

1. **The Tutorials landing is a menu, not a path.** Three cards (Miden Bank, Recipes, Miden Node Setup) with no recommended order. Quick Start's last page (`docs/builder/get-started/your-first-smart-contract/test.md:301-311`) sends to "the Tutorials section" without a specific commit. New builders finish Quick Start and have to guess what to do next.

2. **MASM is hidden under a "Rust" label.** Of the 12 pages in `Recipes > Rust`, 8 author custom MASM contracts and 4 use only standard MASM components (BasicWallet, P2ID) via the Rust client. A reader searching the sidebar for MASM finds nothing.

3. **The Helpers cluster has three different labels** for the same node: folder name `helpers/`, `_category_.json` label `Guides`, `sidebars.ts` override `Development helpers`. Three labels for one node is a strong signal of unsettled IA.

Plus a smaller issue: `miden_node_setup.md` sits inside Tutorials but is operator content (6 bash blocks to run a local node), not a tutorial.

## Proposed Tutorials sidebar

Deltas marked: `↺` rewritten copy, `+` added, `−` removed.

```
Tutorials
├── ↺ Introduction (landing rewritten: CardGrid leads with Miden Bank as recommended;
│ "Two authoring paths" callout owned at the Tutorials layer)
├── Miden Bank (unchanged content; explicitly designated post-Quick-Start canonical
│ next step via the landing CardGrid eyebrow and a terminal Quick Start link)
├── Recipes
│ ├── + Rust (NEW empty placeholder for Rust-compiler recipes; index page only today,
│ │ reserved for AMM, vault, etc. when written)
│ ├── ↺ MASM (RENAMED from "Rust"; today's MASM-authoring pages live here)
│ └── ↺ Web / TypeScript (intro rewritten for explicit Web SDK / React SDK framing;
│ bridging tutorial joins from [#297](https://github.com/0xMiden/docs/pull/297) + [0xMiden/tutorials#199](https://github.com/0xMiden/tutorials/pull/199))
├── ↺ Helpers (RENAMED from "Development helpers"; folder, `_category_.json`, and
│ `sidebars.ts` override all agree on this label)
└── − Miden Node Setup (REMOVED from Tutorials, moved to Tools)
```

Quick Start side: `your-first-smart-contract/test.md` gets a single terminal link to Miden Bank instead of the current generic "Visit the Tutorials section" pointer.

Tools side: `miden_node_setup.md` joins `clients/local-node-testing.md` under Tools.

## Rationale

### **Quick Start to Miden Bank: one coherent path**

Today the last Quick Start page ends with a generic CardGrid pointing into the Tutorials section. New builders see three cards with no recommendation. Most peer protocols I checked (Aptos, Sui, Starknet, NEAR) commit to one explicit next step out of Quick Start.

Proposal: rewrite the terminal "Next Steps" section to a single "Next: Build the Miden Bank" link, with one sentence on why. The Tutorials landing CardGrid eyebrows make the same commit ("Start here · Rust compiler" on the Miden Bank card).

### **Rename `Recipes > Rust` to `Recipes > MASM`**

Of the 12 pages in `Recipes > Rust`, 8 ship custom MASM contracts:

- `counter_contract`, `creating_notes_in_masm`, `custom_note_how_to`, `mappings_in_masm`, `public_account_interaction`, `foreign_procedure_invocation`, `oracle`, `network_transactions`

4 use only standard MASM components (BasicWallet, P2ID notes) via the Rust client without authoring custom MASM:

- `create_deploy`, `mint_consume_create`, `unauthenticated_note_how_to`, `delegated_proving`

The "Rust" label hides what the majority of the cluster actually teaches. Renaming makes MASM visible by name. The 4 SDK-only recipes need a home; see Open Question 1.

### **Reserve `Recipes > Rust` for Rust-compiler recipes**

Today the only pure-Rust-compiler tutorial in the docs is Miden Bank (10 parts). When Rust-compiler recipes are written, they'd need a clear slot. A new `Recipes > Rust` placeholder reserves it. For now we can skip that, but I just want to surface that so that we can keep that in mind ofr the future once we create Rust compiler recipes."

### **Two authoring paths callout at tutorials docs**

The Tutorials landing is where a new builder has to choose between Rust compiler and MASM. The choice belongs on the page where it has to happen, not deferred to Reference. Draft copy:

> Miden lets you write smart contracts in two ways:
>
> - **MASM** (Miden Assembly) is the language Miden's VM executes natively. You get full control and the smallest proof footprint. MASM is the path production projects use today. The recipes under [Recipes → MASM](./recipes/masm/) show how to build, deploy, and drive MASM contracts from a Rust client.
> - **The Rust compiler** translates Rust into MASM for you. It's the fastest way to a working contract: Quick Start and the [Miden Bank](./miden-bank/) walkthrough teach this path. The Rust compiler is the right starting point for most new builders. It's still adding features; projects that need control beyond what the compiler currently emits should reach for MASM.

This wording does not say "the Rust compiler is not production-ready" (off-limits for public docs) but does name MASM as "the path production projects use today" so the production-readiness signal stays honest.

### **Move `miden_node_setup.md` to Tools**

The page is operator content (6 bash blocks to run a local node). It sits next to `clients/local-node-testing.md` in Tools naturally. One workflow change in `.github/workflows/deploy-docs.yml`, one redirect rule in `docusaurus.config.ts`, one sidebar entry move.

### **Resolve the Helpers label inconsistency**

Today: folder name `helpers/`, `_category_.json` label `Guides`, `sidebars.ts` override `Development helpers`. Three labels for one node. Pick `Helpers` everywhere.

## Bridging and PSM tutorial placement

The bridging tutorial (from [#297](https://github.com/0xMiden/docs/pull/297) + [`0xMiden/tutorials#199`](https://github.com/0xMiden/tutorials/pull/199)) currently lands under `Recipes > Web / TypeScript`. I think it should be promoted to a top-level `Tutorials > Bridging` slot, sibling of Miden Bank. Same for PSM tutorials (Guardian, Private Multisig) when they're written.

Major capabilities deserve their own discoverable Tutorials home. Bridging already gets a top-level `Tools > Bridging` slot ([#299](https://github.com/0xMiden/docs/issues/299) / [#300](https://github.com/0xMiden/docs/pull/300)); Guardian and Multisig already get top-level Solutions sections. Burying their tutorial walkthroughs under a generic Recipes cluster doesn't match the weight of the capability and makes them harder to find on the post-Quick-Start journey.

[#297](https://github.com/0xMiden/docs/pull/297) would need a sidebar update; [`0xMiden/tutorials#199`](https://github.com/0xMiden/tutorials/pull/199) would either need the source file moved (out of `docs/src/web-client/`) or a new workflow ingest rule.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.