Clarify more concisely how concepts relate to each other (#64)

* refactor: add overview to introduction

Signed-off-by: Victor Adossi <[email protected]>
Co-authored-by: itowlson <[email protected]>

* fix: phrasing for released versions in intro

Co-authored-by: Kate Goldenring <[email protected]>

* refactor: create new component model concepts section

Signed-off-by: Victor Adossi <[email protected]>

* fix: capitalization

Co-authored-by: Kate Goldenring <[email protected]>

* fix: version tag

Co-authored-by: Kate Goldenring <[email protected]>

* fix: wasi dev link

Signed-off-by: Victor Adossi <[email protected]>

---------

Signed-off-by: Victor Adossi <[email protected]>
Co-authored-by: Victor Adossi <[email protected]>
Co-authored-by: Victor Adossi <[email protected]>
Co-authored-by: Kate Goldenring <[email protected]>

Author: 3 people

component-model/src/SUMMARY.md

@@ -6,11 +6,12 @@
 # Understanding Component Model
 
 - [Why the Component Model?](./design/why-component-model.md)
-- [Components](./design/components.md)
-- [Interfaces](./design/interfaces.md)
-- [Worlds](./design/worlds.md)
-- [WIT](./design/wit.md)
-- [Packages](./design/packages.md)
+- [Component Model Concepts](./design/component-model-concepts.md)
+  - [Components](./design/components.md)
+  - [Interfaces](./design/interfaces.md)
+  - [Worlds](./design/worlds.md)
+  - [Packages](./design/packages.md)
+- [WIT Reference](./design/wit.md)
 
 # Using Component Model
 

component-model/src/design/component-model-concepts.md

@@ -0,0 +1,30 @@
+## Component Model Concepts
+
+This section introduces the core concepts and [rationale](./why-component-model.md) of the component model.
+
+* A [WebAssembly Component](./components.md) is the next evolution of core WebAssembly binaries.
+  * WebAssembly components are *nestable* -- they may contain one or more core modules and/or sub-components composed together.
+* The Component Model extends core WebAssembly by introducing higher level types and interface-driven development
+  * [WebAssembly Interface Types (WIT)][wit] is the [IDL (Interface Definition Language)][wiki-idl] used to formally define functionality for WebAssembly modules.
+  * With WIT, WebAssembly components gain the ability to conform an language-agnostic and encode that support, so any WebAssembly component binary can be interrogated *and* executed.
+  * An [Interface](./interfaces.md) describes the types and functions used for a specific, focused bit of functionality.
+  * A [World](./worlds.md) assembles interfaces to express what features a component offers, and what features it depends on.
+  * A [Package](./packages.md) is a set of WIT files containing a related set of interfaces and worlds.
+* The Component Model introduces the idea of a "platform" to core WebAssembly -- enabling the structured, standardized use of "host" functionality for WebAssembly "guest"s.
+  * The WebAssembly System Interface (WASI) defines in WIT a family of interfaces for common system-level functions.
+  * WASI defines common execution environments such as the command line (`wasi:cli`) or a HTTP server (`wasi:http`).
+* The Component Model introducs makes core WebAssembly composable -- components that provide functionality and those that use them can be composed together into *one* resulting component
+
+> [!NOTE]
+> The Component Model is stewarded by the Bytecode Alliance and designed [in the open][cm-repo].
+>
+> See the [`WebAssembly/component-model`][cm-repo] repository for [Goals][goals],[use cases][use-cases], and [high level design choices][design-choices].
+
+[cm-repo]: https://github.com/WebAssembly/component-model
+[wiki-idl]: https://en.wikipedia.org/wiki/Web_IDL
+[goals]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Goals.md
+[use-cases]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/UseCases.md
+[design-choices]: https://github.com/WebAssembly/component-model/blob/main/design/high-level/Choices.md
+[wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md
+
+[!NOTE]: #

component-model/src/introduction.md

@@ -1,6 +1,6 @@
 # Home
 
-The WebAssembly Component Model is a broad-reaching architecture for building interoperable Wasm libraries, applications, and environments.
+The WebAssembly Component Model is a broad-reaching architecture for building interoperable WebAssembly libraries, applications, and environments.
 
 | Understanding components | Building components  | Using components  |
 |--------------------------|----------------------|-------------------|
@@ -27,14 +27,22 @@ The WebAssembly Component Model is a broad-reaching architecture for building in
 [Running]: ./creating-and-consuming/running.md
 [Distributing]: ./creating-and-consuming/distributing.md
 
-> This documentation is aimed at _users_ of the component model: developers of libraries and applications. _Compiler and Wasm runtime developers_ can take a look at the [Component Model specification](https://github.com/WebAssembly/component-model) to see how to add support for the component model to their project.
+> [!NOTE]
+>This documentation is aimed at _users_ of the component model: developers of libraries and applications.
+>
+> _Compiler and Wasm runtime developers_ can take a look at the [Component Model specification](https://github.com/WebAssembly/component-model) to
+> see how to add support for the component model to their project.
 
 ## Status
 
-[WASI 0.2.0 was released](https://github.com/WebAssembly/WASI/pull/577) Jan 25, 2024, providing a stable release of WASI and the component model. This [is a stable set of WIT definitions](https://github.com/WebAssembly/WASI/tree/main/wasip2) that components can target. WASI proposals will continue to evolve and new ones will be introduced; however, users of the component model can now pin to the stable 0.2.0 release.
+[WASI 0.2.0 was released](https://github.com/WebAssembly/WASI/pull/577) Jan 25, 2024, providing a stable release of WASI and the component model.
+This [is a stable set of WIT definitions](https://github.com/WebAssembly/WASI/tree/main/wasip2) that components can target. WASI proposals will
+continue to evolve and new ones will be introduced; however, users of the component model can now pin to any stable release >= `v0.2.0`. See [WASI.dev](https://www.wasi.dev) to stay up to date on the latest releases.
 
 ## Contributing
 
 If you find a mistake, omission, ambiguity, or other problem, please let us know via [GitHub issues](https://github.com/bytecodealliance/component-docs/issues).
 
 If you'd like to contribute content to the guide, please see the [contribution guide](https://github.com/bytecodealliance/component-docs/blob/main/CONTRIBUTING.md) for information on how to contribute.
+
+[!NOTE]: #

component-model/src/language-support/rust.md

@@ -559,3 +559,5 @@ If you are hosting a Wasm runtime, you can export a resource from your host for
 [cargo-component]: https://github.com/bytecodealliance/cargo-component
 [cargo-component-install]: https://github.com/bytecodealliance/cargo-component#install
 [docs-adder]: https://github.com/bytecodealliance/component-docs/tree/main/component-model/examples/tutorial/wit/adder/world.wit
+[!NOTE]: #
+[!WARNING]: #