Design: How to teach WebAssembly / bring new people up to speed

[qwertie]

I've always wanted to see some articles about Wasm that would help explain ...

• The use cases where Wasm excels (like PR #449 tries to say)
• Design goals .... if I may digress: HighLevelGoals.md covers some of this, but isn't, I think, clear enough: it doesn't mention about how _agressively_ Wasm pursues security; it doesn't mention avoidance of nondeterminism (a recurring theme that I definitely sense is a "design goal"); it says "size- and load-time-efficient" but doesn't say that the goal is specifically to do _better_ than JS/asm.js; it doesn't mention another recurring theme, that our thinking is often inspired by the Extensible Web Manifesto; it says the text format is "convertible to and from the binary format" but doesn't say how faithful the conversion must be (e.g. preservation of variable names?); and it doesn't talk about simplicity which I think is another tacit goal. Also, a nit, "execute at native speed" is important enough to warrant its own bullet point. Finally, something that makes me happy, I have a sense that eventually supporting _all_ known programming languages semi-efficiently is a tacit goal (not in MVP, but someday). I bet it'll run Swift and D and C# really well someday.
• Non-goals (e.g. openness-by-default by being decompiler-friendly, and cross-language interoperability, two issues I deeply care about) and how the design of WebAssembly could _allow_ those non-goals to be met by separate people or groups in the future.
• Parts of WebAssembly that are NOT complete
• Actual concrete design elements by example (e.g. I'd like to see what a complete wasm program looks like, in s-expr form or binary or both, that incorporates many key elements like a loop, switch, if, a function call, and an array in linear memory).
• How to use the spec prototype to compile and run a .wast file, and a C program.

All of these points are about teaching people about WebAssembly, but I noticed resistance to teaching people about WebAssembly via this repo in #232. I'm not sure, perhaps it was just because not enough design decisions had been made at the time, or because I mixed in a text format proposal... But I wonder if there would there be more willingness to have "teaching materials" if they were located somewhere else? A couple of options:

1. Place teaching documents in the gh-pages branch of this repo, and link from README.md to this repo's web page
2. People write these sorts of materials on their own blogs and then we accept PRs for links to be added to README.md.

Also, if we have teaching articles, I think the beginning of each design document should link to a closely related "primer", if available.

[rossberg]

These all sound like good suggestions, but it seems a bit early to worry about "teaching". We are still iterating on the initial design (including goals), there is no fully functional implementation yet, and so on. Anything written outside the repo would probably be outdated a few days later. I think creating material like that will start making more sense once the MVP is stable, hopefully in a couple of months.

[jcbeyler]

I agree with rossberg, we are still too early. I think that we could do a series of blogs or short things that would show where we are up to. So something more than just the twitter.

But anything as big as what you say would mean that you would have to update the teaching documents and the design at the same time and I think that overhead is not yet warranted

[data-ux]

I'm firm believer in learning by doing and that's why I have published a WASM playground where people can see for themselves how WASM works on the semantics level:
http://ast.run/

I think this kind of tools/toys can be very useful in teaching about WASM even though real applications won't be written in WASM but compiled from higher level languages.

[qwertie]

@data-ux How does the editor work? Is the source code available?

[data-ux]

The user is directly manipulating the WebAssembly AST, which is rendered to html on the fly. The interpretation of the WASM program is handled by binaryen.js.

The code is here:
https://github.com/data-ux/wasm-playground

[binji]

@data-ux I just pushed a similar demo using sexpr-wasm. Not nearly as fancy, but it's fast and gives nice errors.

P.S. newer version

[kripken]

@binji: very nice!

[binji]

@kripken just don't look at my C to JS binding code :blush:

[data-ux]

@binji, nice demo! The generated descriptions are very informative.

[yurydelendik]

We probably need to turn this issue into wiki page with set of links to the demos.

Here is another one: http://mbebenita.github.io/WasmExplorer/ . It is a C-to-wast translator via web service, plus it demonstrates compilation of the WebAssembly to machine code on a browser side (it's only SpiderMonkey on x86/64-bit architecture atm).

/cc @mbebenita

[jfbastien]

@s3ththompson has done a bunch of work recently to improve this situation. Closing this issue. Please file smaller issues for anything that's missing from newer work.