First draft proposal for table of contents #1
Conversation
|
|
||
| This is presented as plain Markdown for easy discussion and iteration. The final form would likely be a `mdbook` SUMMARY document, but that doesn't allow for inline comments and explanations. | ||
|
|
||
| The intent of this book would be to target Preview 2 only. Discussion of future ambitions would be clearly ring-fenced to a roadmap section. |
There was a problem hiding this comment.
I think this is just nit pick, but I believe the concept of Preview 2 only exists in WASI, not in Wasm Component Model spec. Considering this is a book for Wasm Component Model, could we be more precise about the scope of this book?
There was a problem hiding this comment.
@Mossaka This was based on the Component Model repo README which refers to 'the "Preview 2" milestone' and contrasts it with a future Preview 3 milestone. https://github.com/WebAssembly/component-model#milestones
There was a problem hiding this comment.
Another way to phrase this might be something like:
This book is expected to evolve alongside the Component Model and WASI projects, with an initial release targeting the WASI Preview 2 milestone and associated Component Model features. For more information about this milestone and a longer-term roadmap, see WebAssembly: An Updated Roadmap for Developers.
| - **Goals and Principles** - *Focuses on covering all the "whys"* | ||
| - **WIT Overview** - *explained through an annotated WIT interface* | ||
| - **Concepts** - *concepts build upon each other. example oriented rather than just a reference* | ||
| - **Interfaces** |
There was a problem hiding this comment.
I am not sure if the concept items listed here have an ordering or not. If there is an order, I'd put worlds before packages.
| - **Creating and Consuming Components** - *how to author a component, combine components, call components, validate a component, distribute a component* | ||
| - **Language Support** | ||
| - **C** | ||
| - **Rust** |
There was a problem hiding this comment.
I would add a few more languages, such as Go, Python, JavaScript, which are actively being worked on under the BCA's Guest Langauge SIG
There was a problem hiding this comment.
This was intended as indicative but definitely!
component-model/README.md
Outdated
| @@ -0,0 +1,38 @@ | |||
| # Component model proposed table of contents | |||
|
|
|||
| This is presented as plain Markdown for easy discussion and iteration. The final form would likely be a `mdbook` SUMMARY document, but that doesn't allow for inline comments and explanations. | |||
component-model/README.md
Outdated
| - **What is a Component?** | ||
| - **Use Cases** | ||
| - **Features of Components** | ||
| - **How Components are Physically Represented** |
There was a problem hiding this comment.
Should we add differences between modules and components?
There was a problem hiding this comment.
I could see us having a section on how components relate to modules in that they consist of them. We could then add a callout to go learn about modules and come back, similar to what @rylev does in his component book: https://wasm-components.fermyon.app/encoding.html#core-webassembly-modules
There was a problem hiding this comment.
I think that for most users this is more than they need to know. Perhaps this should be in the advanced section?
There was a problem hiding this comment.
I would expect a brief description of the relationship between components and models to be part of some overview section.
itowlson
force-pushed
the
initial-draft-toc-proposal
branch
from
55ad167 to
43abd81
Compare
|
I have updated with the feedback here. Thanks all! |
| - Tutorial | ||
| - C | ||
| - Rust | ||
| - Overview and Design |
There was a problem hiding this comment.
IMO, a logical sequencing of how end users would consume documentation would be to:
- read an overview,
- understand the concepts followed by some examples,
- and then go try out some tutorials - hands on or otherwise.
The language support + reference documentation can come thereafter.
| - **Future Directions** | ||
| - **Implementations** - *where can I run components (runtimes, languages, etc)* | ||
| - **Tutorial** - *an example to jump into using components. Involves downloading wasm-tools. Maybe this [wasm compose](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-compose/example) example or Ryan Levick's walkthrough in his [components book](https://github.com/rylev/component-book)* | ||
| - **What is a Component?** - *Might include 'differences between modules and components' as a specific section or page* |
There was a problem hiding this comment.
IMO, the logical sequencing on how a user would potentially consume this book would be :
- Introduction to the Component Model
- Design (Explaining the why)
- What is a component (Explaining the what)
- Concepts (talking about some peripheral stuff incorporating the ordering suggestions that @Mossaka has provided)
- Creating & consuming components (Explaining the how by tying into previous sections)
- Examples (showing them how it is done building upon knowledge from previous sections)
- Tutorials (where the user can directly go and try things out for themselves)
- Language support
- Advanced topics
- WIT Reference documentation
- Additional reference documentation
| - **How Types are Laid Out in Memory** | ||
| - **Function Arguments and Results** | ||
| - **Memory Management** | ||
| - **Examples** |
There was a problem hiding this comment.
I really like the approach to examples taken by the Rust Cookbook. I wonder if something like that would work better as a separate document, though, or even an entirely separate publication that specialises in being able to present and automatically test, e.g. , N different versions (languages) of an example?
If that doesn't belong here and nobody else is working on it, I'd consider starting it myself. (However my lack of free time right now 👨👩👧👦 means I'm unlikely to actually follow through on this.)
There was a problem hiding this comment.
Are you thinking of the Rust by example book? That would be a great addition!
There was a problem hiding this comment.
I was actually thinking about this one: https://rust-lang-nursery.github.io/rust-cookbook/. But Rust by Example is a great source of inspiration, too!
The audience I have in mind is someone who wants to do X thing that involves Wasm Components, but isn't really sure how it fits in to the big picture or how to get started.
In my mind, there would be individual articles for different common/requested/anticipated use cases, with some discussion of an approach and code samples, so it would cover the how and the why of the suggested solution.
I also imagine there being a top-level switch for preferred host and guest language, and each article would adapt to reflect your preference — mostly just the code samples, but potentially also other snippets relating to language specific tooling.
|
@jeffparsons' excellent idea reminded me that we should capture the outstanding suggestions from the discussion on this PR and then close it in favour of creating new issues -- this was never really a merge candidate and is even less of one now! |
|
@itowlson @kate-goldenring I've gone through all the open comments and created issues for any that weren't already captured. I think this PR can be closed now. |
|
Thank you @rylev for capturing the final pieces. Closing |
Getting the ball rolling! Thanks to @kate-goldenring for all the work on this!