I'd like to use this issue as a tracking issue for filling out gaps in wasmtime's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)

Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!

Book Documentation

As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!

• Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the wasmtime CLI to execute a Rust-generated WebAssembly file - @noculture
• List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
• Documenation of using wasm from Python - @jjsullivan5196
• Documentation of using wasm from .NET
• Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
• Documentation of using wasm from bash (aka examples of using the CLI)
• Writing WebAssembly from C/C++
• Writing WebAssembly, markdown example - @humancalico
• Embedding wasmtime overview
• Embedding wasmtime in Rust - currently has docs but feels a bit light on content
• Embedding wasmtime in C/C++
• Embedding wasmtime in .NET - probably want a page on this?
• What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
• Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
• Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
• Security policy
• Disclosure policy
• Sandboxing - @sunfishcode
• Governance

API Documentation

• The crate documentation feels lacking and could use a broad example to introduce the crate.
• The Module type should have at least one example somewhere.
• The Instance type should have at least one example.
• The Store type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.
• The Memory type needs examples of safe usage, and double-checks on wording about unsafe usage.
• The Func type could use an example on the get family of methods.
• Types which correspond to the wasm specification should link there where possible.

Examples

I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:

• Move Rust examples to a top-level examples directory - @alexcrichton
• Move C examples to the top-level examples directory too - @alexcrichton
• Every example has a comment at the top of the file of how to build and run it - @alexcrichton
  • Rust is typically cargo run --example foo
  • C is gcc examples/foo.c -I crates/c-api/include -o foo && ./foo (ish)
• Wasm files are never checked in for examples - @alexcrichton
  • Either wasm is written inline as a *.wat string
  • Or example is structured as examples/name/main.rs with a corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/name/wasm.c if we want to show off a C-compiled wasm example)
• Every example is available in both Rust and C - @alexcrichton
  • For examples/foo.rs we have a corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/foo/main.c
• Example showing how to link in the WASI functions
• Example of reading a string from a wasm module
• Example of a string processor, for example a markdown renderer
• All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton