refactor: Revise introduction (#280)

* Revise introduction

* Update component-model/src/introduction.md

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

* More detail on platforms / what APIs are for

---------

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

Author: catamorphism

component-model/src/SUMMARY.md

@@ -3,7 +3,7 @@
 
 - [Introduction](./introduction.md)
 
-# Understanding Component Model
+# Understanding WebAssembly Components
 
 - [Why the Component Model?](./design/why-component-model.md)
 - [Component Model Concepts](./design/component-model-concepts.md)
@@ -13,7 +13,7 @@
   - [Packages](./design/packages.md)
 - [WIT Reference](./design/wit.md)
 
-# Using Component Model
+# Using WebAssembly Components
 
 - [Language Support for Components](./language-support.md)
   - [C/C++](./language-support/c.md)

component-model/src/introduction.md

@@ -2,6 +2,15 @@
 
 The WebAssembly Component Model is a broad-reaching architecture for building interoperable WebAssembly libraries, applications, and environments.
 
+This documentation is aimed at _users_ of the component model: developers of libraries and applications.
+
+> [!NOTE]
+>
+> _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.
+
+## Table of contents
+
 | Understanding components | Building components  | Using components  |
 |--------------------------|----------------------|-------------------|
 | [Why Components?]        | [C/C++]              | [Composing]       |
@@ -27,17 +36,55 @@ The WebAssembly Component Model is a broad-reaching architecture for building in
 [Running]: ./running-components.md
 [Distributing]: ./composing-and-distributing/distributing.md
 
-> [!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
+## WebAssembly components
+
+As with all programming, the goal of writing a component
+is to make new functionality available
+by building it out of existing functionality.
+
+A WebAssembly component runs on a _platform_,
+which may be a Web browser,
+a stand-alone runtime,
+or even an operating system (when compiling WebAssembly to an executable).
+By running the component, the platform gains the functionality
+that the component implements.
+Likewise, the platform provides functionality
+that code in components can use to interact
+with the outside world.
+
+For example:
+
+- A user of the component model can build a component
+  that converts the system time to another time zone.
+- For the component to work as intended, the underlying platform
+  must provide the component with a means to access
+  the current system time and the system time zone.
+
+## APIs for building WebAssembly components
+
+In general, a platform that runs components
+must provide well-defined APIs for accessing functionality
+that components need:
+for example, reading from standard input,
+accessing environment variables,
+or manipulating network sockets.
+
+It's useful to have a standard, shared set of APIs
+that WebAssembly components can depend on.
+[WASI](https://wasi.dev/) (the WebAssembly System Interface) is a standards-track specification
+that defines these APIs.
+A system or platform may expose some or all of the WASI APIs to components.
+
+### 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 any stable release >= `v0.2.0`. See [WASI.dev](https://wasi.dev) to stay up to date on the latest releases.
+The current stable release of WASI is [WASI 0.2.0](https://github.com/WebAssembly/WASI/pull/577),
+which was released on January 25, 2024.
+WASI 0.2.0 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`.
+The [WASI.dev roadmap](https://wasi.dev/roadmap) tracks upcoming releases.
 
 ## Contributing
 

component-model/src/reference/faq.md

@@ -143,7 +143,7 @@ The component is said to "export" the `example-interface` interface, making avai
 ## Still have questions?
 
 Please contribute to the Component Book by filing your question (or one that you think should be covered here) as
-[an issue on GitHub][gh-issues].
+[an issue on GitHub][gh-issues-new].
 
 [gh-issues-new]: https://github.com/bytecodealliance/component-docs/issues/new