Skip to content

Commit cd9d6cc

Browse files
avrabeavrabe
committed
feat: restructure documentation with improved information architecture
Reorganize documentation from 11 overwhelming sections to 4 clear content types following best practices from Vue.js, Kubernetes, MDN, and Rust Book: - GET STARTED: Quick success and clear user path guidance - LEARN: Conceptual understanding separated by technology domain - BUILD: Task-oriented practical guides with thematic organization - REFERENCE: Quick lookup with thematic grouping (WIT, Language, Composition, Security rules) Key improvements: - Add prominent "Pick Your Learning Path" page with explicit user type guidance - Create "WebAssembly Component Fundamentals" separating technology concepts from Bazel usage - Break up massive rule reference into discoverable thematic groups - Add complexity indicators (Beginner/Intermediate/Advanced) with visual badges - Implement responsive design improvements and better navigation structure - Fix cross-references and improve content discoverability Reduces cognitive load while maintaining excellent technical depth and visual quality. Addresses information architecture overload and unclear user journeys.
1 parent 909899e commit cd9d6cc

File tree

10 files changed

+1873
-75
lines changed

10 files changed

+1873
-75
lines changed

‎docs-site/astro.config.mjs‎

Lines changed: 63 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -44,95 +44,83 @@ export default defineConfig({
4444
},
4545
sidebar: [
4646
{
47-
label: 'Getting Started',
47+
label: 'GET STARTED',
4848
items: [
49-
{ label: 'Learning Path', slug: 'learning-path' },
49+
{ label: '👋 Pick Your Learning Path', slug: 'pick-your-path' },
5050
{ label: 'Zero to Component in 2 Minutes', slug: 'zero-to-component' },
51-
{ label: 'Quick Start', slug: 'getting-started' },
52-
{ label: 'Installation', slug: 'installation' },
53-
{ label: 'First Component', slug: 'first-component' },
51+
{ label: 'Installation & Setup', slug: 'installation' },
5452
],
5553
},
5654
{
57-
label: 'Architecture',
55+
label: 'LEARN',
5856
items: [
59-
{ label: 'Overview', slug: 'architecture/overview' },
60-
{ label: 'Development Workflow', slug: 'workflow/development-flow' },
57+
{ label: 'WebAssembly Component Fundamentals', slug: 'learn/fundamentals' },
58+
{ label: 'Component Architecture', slug: 'architecture/overview' },
59+
{ label: 'Multi-Language Development', slug: 'guides/wit-bindgen-interface-mapping' },
60+
{ label: 'Tutorials', collapsed: true, items: [
61+
{ label: 'Code Explained Line by Line', slug: 'tutorials/code-explained' },
62+
{ label: 'First Component Tutorial', slug: 'first-component' },
63+
{ label: 'Guided Rust Walkthrough', slug: 'tutorials/rust-guided-walkthrough' },
64+
{ label: 'Guided Go (TinyGo) Walkthrough', slug: 'tutorials/go-guided-walkthrough' },
65+
]},
6166
],
6267
},
6368
{
64-
label: 'Tutorials',
69+
label: 'BUILD',
6570
items: [
66-
{ label: 'Code Explained Line by Line', slug: 'tutorials/code-explained' },
67-
{ label: 'Guided Rust Walkthrough', slug: 'tutorials/rust-guided-walkthrough' },
68-
{ label: 'Guided Go (TinyGo) Walkthrough', slug: 'tutorials/go-guided-walkthrough' },
71+
{ label: 'Language Development', collapsed: false, items: [
72+
{ label: 'Rust Components', slug: 'languages/rust' },
73+
{ label: 'Go Components', slug: 'languages/go' },
74+
{ label: 'JavaScript & TypeScript', slug: 'languages/javascript' },
75+
{ label: 'C & C++', slug: 'languages/cpp' },
76+
]},
77+
{ label: 'Common Patterns', collapsed: true, items: [
78+
{ label: 'WIT Bindgen Interface Mapping', slug: 'guides/wit-bindgen-interface-mapping' },
79+
{ label: 'WIT Bindgen Advanced Concepts', slug: 'guides/wit-bindgen-advanced-concepts' },
80+
{ label: 'Guest vs Native-Guest Bindings', slug: 'guides/host-vs-wasm-bindings' },
81+
{ label: 'Performance Optimization', slug: 'production/performance' },
82+
{ label: 'Advanced Features', slug: 'guides/advanced-features' },
83+
]},
84+
{ label: 'Examples', collapsed: true, items: [
85+
{ label: 'Basic Component', slug: 'examples/basic' },
86+
{ label: 'Basic Examples', slug: 'examples/basic-examples' },
87+
{ label: 'Intermediate Examples', slug: 'examples/intermediate-examples' },
88+
{ label: 'Advanced Examples', slug: 'examples/advanced-examples' },
89+
{ label: 'WIT Bindgen Interface Mapping', slug: 'examples/wit-bindgen-with-mappings' },
90+
{ label: 'Calculator (C++)', slug: 'examples/calculator' },
91+
{ label: 'HTTP Service (Go)', slug: 'examples/http-service' },
92+
{ label: 'Multi-Language System', slug: 'examples/multi-language' },
93+
]},
94+
{ label: 'Composition & Deployment', collapsed: true, items: [
95+
{ label: 'WAC Composition', slug: 'composition/wac' },
96+
{ label: 'WAC + OCI Integration', slug: 'composition/wac-oci-integration' },
97+
{ label: 'OCI Publishing', slug: 'production/publishing' },
98+
{ label: 'Deployment Guide', slug: 'production/deployment-guide' },
99+
{ label: 'Component Signing', slug: 'security/component-signing' },
100+
{ label: 'OCI Component Signing', slug: 'security/oci-signing' },
101+
]},
102+
{ label: 'Configuration & Tooling', collapsed: true, items: [
103+
{ label: 'Toolchain Configuration', slug: 'guides/toolchain-configuration' },
104+
{ label: 'Multi-Profile Builds', slug: 'guides/multi-profile-builds' },
105+
{ label: 'External WIT Dependencies', slug: 'guides/external-wit-dependencies' },
106+
{ label: 'Migration Guide', slug: 'guides/migration' },
107+
{ label: 'Development Workflow', slug: 'workflow/development-flow' },
108+
]},
109+
{ label: 'Troubleshooting', collapsed: true, items: [
110+
{ label: 'Common Issues & Solutions', slug: 'troubleshooting/common-issues' },
111+
{ label: 'Export Macro Visibility', slug: 'troubleshooting/export-macro-visibility' },
112+
{ label: 'WIT Bindgen Troubleshooting', slug: 'guides/wit-bindgen-troubleshooting' },
113+
]},
69114
],
70115
},
71116
{
72-
label: 'Languages',
117+
label: 'REFERENCE',
73118
items: [
74-
{ label: 'Rust Components', slug: 'languages/rust' },
75-
{ label: 'Go Components', slug: 'languages/go' },
76-
{ label: 'JavaScript & TypeScript', slug: 'languages/javascript' },
77-
{ label: 'C & C++', slug: 'languages/cpp' },
78-
],
79-
},
80-
{
81-
label: 'Guides',
82-
items: [
83-
{ label: 'Guest vs Native-Guest Bindings', slug: 'guides/guest-vs-native-guest-bindings' },
84-
{ label: 'Advanced Features', slug: 'guides/advanced-features' },
85-
{ label: 'Migration Guide', slug: 'guides/migration' },
86-
{ label: 'Toolchain Configuration', slug: 'guides/toolchain-configuration' },
87-
{ label: 'Multi-Profile Builds', slug: 'guides/multi-profile-builds' },
88-
{ label: 'External WIT Dependencies', slug: 'guides/external-wit-dependencies' },
89-
],
90-
},
91-
{
92-
label: 'Examples',
93-
items: [
94-
{ label: 'Basic Component', slug: 'examples/basic' },
95-
{ label: 'Basic Examples', slug: 'examples/basic-examples' },
96-
{ label: 'Intermediate Examples', slug: 'examples/intermediate-examples' },
97-
{ label: 'Advanced Examples', slug: 'examples/advanced-examples' },
98-
{ label: 'Calculator (C++)', slug: 'examples/calculator' },
99-
{ label: 'HTTP Service (Go)', slug: 'examples/http-service' },
100-
{ label: 'Multi-Language System', slug: 'examples/multi-language' },
101-
],
102-
},
103-
{
104-
label: 'Composition',
105-
items: [
106-
{ label: 'WAC Composition', slug: 'composition/wac' },
107-
{ label: 'WAC + OCI Integration', slug: 'composition/wac-oci-integration' },
108-
],
109-
},
110-
{
111-
label: 'Security',
112-
items: [
113-
{ label: 'Component Signing', slug: 'security/component-signing' },
114-
{ label: 'OCI Component Signing', slug: 'security/oci-signing' },
115-
],
116-
},
117-
{
118-
label: 'Production',
119-
items: [
120-
{ label: 'Deployment Guide', slug: 'production/deployment-guide' },
121-
{ label: 'OCI Publishing', slug: 'production/publishing' },
122-
{ label: 'Performance Optimization', slug: 'production/performance' },
123-
],
124-
},
125-
{
126-
label: 'Troubleshooting',
127-
items: [
128-
{ label: 'Common Issues & Solutions', slug: 'troubleshooting/common-issues' },
129-
{ label: 'Export Macro Visibility', slug: 'troubleshooting/export-macro-visibility' },
130-
],
131-
},
132-
{
133-
label: 'Reference',
134-
items: [
135-
{ label: 'Rule Reference', slug: 'reference/rules' },
119+
{ label: 'WIT & Interface Rules', slug: 'reference/wit-interface-rules' },
120+
{ label: 'Language Rules', slug: 'reference/language-rules' },
121+
{ label: 'Composition Rules', slug: 'reference/composition-rules' },
122+
{ label: 'Security Rules', slug: 'reference/security-rules' },
123+
{ label: 'Complete Rule Reference', slug: 'reference/rules' },
136124
],
137125
},
138126
],

‎docs-site/src/content/docs/languages/rust.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,16 @@ title: Rust Components
33
description: Build WebAssembly components with Rust using rules_rust integration
44
---
55

6+
# Rust Components
7+
8+
<div class="complexity-badge intermediate">
9+
<span class="badge-icon">🦀</span>
10+
<div class="badge-content">
11+
<strong>INTERMEDIATE</strong>
12+
<p>Assumes basic Rust knowledge and some Bazel familiarity</p>
13+
</div>
14+
</div>
15+
616
## Why Rust for WebAssembly Components?
717

818
Rust is the **ideal language** for WebAssembly components. Its zero-cost abstractions, memory safety, and lack of runtime overhead make it perfect for creating fast, secure, portable components.

0 commit comments

Comments
 (0)