Some suggestions for improving "reproducibility" of tutorial

Where in the docs did you come across this? Various locations listed below (NOTE: this likely isn't exhaustive, as I haven't finished going through the tutorial quite yet, but wanted to submit an issue for these ones while they're fresh in my mind, I might follow up with any other places where this issue is encountered if it occurs at later points in the tutorial).

1) https://rustwasm.github.io/docs/book/game-of-life/hello-world.html#whats-inside 2) https://rustwasm.github.io/docs/book/game-of-life/hello-world.html#putting-it-into-a-web-page 3) https://rustwasm.github.io/docs/book/game-of-life/implementing.html 4) https://rustwasm.github.io/docs/book/game-of-life/implementing.html#rendering-with-javascript

Describe what about it does not make sense I guess I should first explain a little about where I'm coming from and what I mean by "reproducibility" in this case. Whenever I'm going through tutorials about a particular topic, it's almost always because 1) I have little to no knowledge/skills in that topic and 2) I would like to gain some basic knowledge/skill in that topic. Because of that, I guess I have the expectation that tutorials will be "easy", in the sense that they require a minimal (if any) amount of "figuring stuff out"/debugging/problem solving (not that it's bad to encourage people to develop those skills, quite the opposite, just imo, not good for a tutorial (with the exception of when something is explicitly described as something to "figure out" with the answer then provided, for example, like the "Exercises" sections at the end of some pages in this tutorial) because again, people going through tutorials are usually beginners, and thus might not even have a sense of what the "correct" answer/behavior should even look like, and it's nearly impossible to problem solve when you're so unfamiliar with something that you're unsure about what the "problem" itself even is).

In other words, when going through a tutorial, I expect to be able to go through it step by step, following each direction exactly, and then have a "correct" answer to compare my result to in order to see if it matches exactly, and that's what I mean by "reproducibility" in this context.

Why does it not make sense? Note: Each number in below list corresponds to the same number in the list for the "where in the docs did you come across this" section.

1) When I run the following command:

cargo generate --git https://github.com/rustwasm/wasm-pack-template

I get a directory structure that, while mostly resembling the one in this section, includes an "extra" test directory that isn't shown in the tutorial. I suspect the reason for this is that the GitHub repo the template is on previously (at the time the tutorial was written) did not have a test directory, but that it got added later, and thus now the tutorial and the referenced GitHub repo are out of sync.

2) As previously stated, when going through tutorials, I don't expect to have to "figure things out", and as such, I expect that if there's any command that I'm supposed to run, it will be explicitly provided, even if seemingly obvious. When going through this tutorial, at the point where I was supposed to run the following command:

npm init wasm-app www

I did NOT get the directory structure that follows it. In fact, I didn't even get a directory called "www", let alone any of its files. At that point, all I could be sure of was "something went wrong", and didn't really understand why right away (and while I did figure out a way to get it to work, I'm still not completely sure if that was "the correct" (as in what the author(s) intended) way to do it.). All that I know is that either: 1) the npm init wasm-app www command should create the "www" directory and initialize its contents (in which case maybe my npm wasn't the right version or was configured incorrectly with wasm), or 2) there's a command that I was supposed to run which wasn't explicitly stated in the tutorial. I think that the 2nd case is likely what happened, and I was able to get the "www" directory by running the following command:

cargo generate --git https://github.com/rustwasm/create-wasm-app

and giving it www at the prompt, but again, that exact command was never explicitly given, just hinted at.

3) Throughout this section, there's many places where small changes are being made to multiple files (in multiple languages) in the project. Because of this, it becomes very likely that someone going through the tutorial might accidentally miss a few changes that they were supposed to make, or might make a few typos which can cause their version to not work as expected. The main issue is that if this happens, there's no quick way to verify that this happened since there aren't any "complete" ("complete", as in up to that point in the tutorial) versions to compare/run diff against.

4) Note: this might relate to 3, where it's possible I got something wrong, but it might also just be that I got everything right and this was misleading. Basically, the image in this section doesn't look like what I got, I think it has to do with the image being from a different initial configuration of the game (in which case, the image should be changed to reflect what one should expect from the initial configuration given in the tutorial, that is, from initializing all cells with indices divisible by either 2 or 7 to be alive and all other cells to be dead). It's "possible" that the image is what should be generated from following the steps in the tutorial, but I wouldn't know for sure unless either problem 3 was solved ;) or if I took the time to actually figure out what the initial configuration should look like on a 64x64 grid (which again, I don't think should be necessary to "figure out" when my main goal is to learn WebAssembly with Rust, but I did anyway, and yeah, the image doesn't match since otherwise every other cell (and every 7th) should be alive at the start, and that's not what's shown in that image).

How could we improve it? Note: Again, numbering corresponds with above sections (some numbers may have multiple suggested fixes).

Possible Short Term Solutions 1) Include the test directory and contents in tutorial for expected directory structure.

2) If the npm init wasm-app www command should create and initialize the "www" directory, then explicitly state that and suggest that there might be a configuration/version issue if the "www" directory doesn't appear, otherwise, if it's indeed that the cargo generate ... command needed to be run, then explicitly state that it does.

3) At the end of every subchapter/section that has a lot of changes being made, give the complete "correct" version of all the files which were changed (possibly as a link) so that people can diff their versions against them and minimize time spent debugging (which again, I don't think should be the focus of a tutorial unless it's explicitly in a "debugging" section of a tutorial, and usually in that case, it's best to guide people through the debugging).

4) Change the image. (might also need to be done in the "It works" section too, but I haven't reached that point in the tutorial yet).

Possible Long Term Solutions 1 & 2) Note: this part might be better to open as an issue with the main rustwasm project (in which case, please let me know, and I'd be happy to do so, or maybe as an RFC for Rust, again, I'm a beginner, so apologies in advance if there was a better place for me to include this suggestion, I don't know any better!), but I've included it here since it could also help improve the tutorial.

My suggestion is to have better tooling/integration with cargo, possibly with something like a "wasm" subcommand for cargo. The motivation for this comes from a few reasons: 1) it could greatly simplify the explanation for the setup portion of the tutorial, thus making it more "beginner friendly", 2) it mitigates the "synchronization" issue from having the tutorial reference an active git repo, and 3) it has the added benefit of making it more convenient to create new wasm projects from scratch. Basically, imo, one of the (many) nice things about using cargo with a non-WebAssembly Rust project is that if I want to create a new project (which I do often when prototyping), all I have to do is run:

cargo new helloworld or cargo new --lib helloworld

and it does all the boilerplate stuff for initializing directories & files with sensible defaults, and the only changes I need to make are ones that are specific to my project (and if I don't think the defaults are good, I can even change those!). I get that the idea of cargo generate ... is to do the same (minimizing boilerplate while still allowing changes to default configuration), but being honest, I don't think it's quite there yet. To demonstrate what I mean by this, compare the cargo new helloworld command (a single command) with what has to be done to get the directory structure from the tutorial (ignoring installation parts of the setup):

cargo generate --git https://github.com/rustwasm/wasm-pack-template wasm-pack build cargo generate --git https://github.com/rustwasm/create-wasm-app (maybe) npm init wasm-app www cd pkg npm link cd ../www npm link wasm-game-of-life

Okay, so it's not that bad, but it's definitely way more than just a single command, and if most of the contents are boilerplate anyway, why shouldn't it be more something like this to get the same resulting directory structure?:

cargo wasm new helloworld cd helloworld cargo wasm build

or (if a few different defaults might be sensible depending on the type of project, and for this one we want to make it a "web" app):

cargo wasm new --web helloworld cd helloworld cargo wasm build

or maybe at worst something like the following (if you want to keep npm stuff separate, which seems like there's a chance that might be a more sensible approach, also note that I've omitted the link commands as I'm assuming the above proposed commands would just create the files with the appropriate configurations to begin with):

cargo wasm new helloworld cd helloworld npm init wasm-app www cargo wasm build

Additionally, I imagine that a large portion of people who are trying to learn WebAssembly with Rust already will have some familiarity with Rust/cargo, so this would also minimize the need to learn new tools for them (even if the proposed wasm subcommand might call into wasm-pack or cargo generate behind the scenes). Further, if the tutorial then references results from this proposed "wasm subcommand", then it would only need to be kept up to date with changes to that, which will likely be less often than an active git repo, thus mitigating (but not eliminating) the synchronization issue. I realize this might be a bit ambitious (also note, I have no idea how difficult/feasible this is, from what I understand, in theory, cargo should be extendable in this way, but admittedly I haven't read the cargo book yet (on my todo list), so idk), but I think it would greatly improve user experience by making the Rust WebAssembly experience more uniform with the standard Rust/cargo experience, and would likely reduce some friction for people who are just starting out with rustwasm (and are likely already familiar with Rust/cargo) to create new projects and get them up and running.

1, 2, 3, & 4) Incorporate the following into the process for updating the rustwasm book (to be done before publishing the update):

Start from beginning to end (either of the book or just the section(s) being changed, depending on how big of an update it is), run every command and make every change to files exactly as described (skipping anything that isn't a code block), and compare to the results you get to the expected results that the tutorial shows. If they don't match exactly, then there's likely a problem with at least one of the following: 1) a missing or wrong command/change to files 2) a missing or wrong expected result from those changes.

I realize this might seem like a lot of tedium even for even simple updates (and if it seems it would likely take too much time away from more important things in this project, feel free to disregard this suggestion, actually feel free to disregard all of these suggestions, I'm not your boss, lol, although I think some (if not all) parts of this process could be automated), but I think it would greatly improve the overall quality of the tutorial by making sure every direction/result is reproducible and making it easier to catch instances of when things aren't.

Side Note I wonder if it might be worth considering using a different project than Conway's Game of Life for this tutorial (or moving it to a later section and/or reworking it a bit). The reason I'm saying this is that at some points in the tutorial, it seems like the focus is more about Conway's Game of Life than it is about using Rust with WebAssembly (for example, the entirety of 4.3 is dedicated to explaining the rules for Conway's Game of Life with nothing about either Rust or WebAssembly, I realize it's not a particularly long section, and it says it can be skipped, but I still feel like it's a bit much to have that much explanation when the main thing people want to take away from this tutorial is how to use Rust with WebAssembly). In general, I think a good principle for coming up with examples in tutorials is to first ask "What are the things about this topic that are important for readers to learn about/how to do?" and then ask "what are some interesting examples which can help demonstrate those concepts?". In this case, I think it's likely that the correct questions were asked, but just in the wrong order. With that said, I still like Conway's Game of Life, and think it's a fun project to build (and it is important to have interesting projects in tutorials, since otherwise people might get bored and not finish the tutorial all the way through), so it might be best to just rework it with those questions in mind (maybe split up the project by each individual WebAssembly concept that part of the project demonstrates, and sprinkle in explanations about the game itself when appropriate, and maybe add a few other simple projects in between helloworld and Conway's Game of Life so that it's built up to more gradually, or maybe make all the projects different ones for each main concept, and then have Conway's Game of Life as an optional "practice your skills" chapter, lots of possibilities, I'm not sure which would be best).

Final Note I hope I don't sound like I'm complaining too much, I really like the tutorial so far and think it's great over all, but just thought I'd provide some feedback and mention that these are some things that I think could be improved upon. I also understand it's quite hard to write tutorials in general, there's sort of a catch-22 with them, if you know enough to be able to write one, then you know too much and it's difficult to read it like a beginner would, so no worries about any of this :) I know it's tough! Also, I don't want to just complain without offering to pitch in a little, so feel free to let me know if there's anything I can do to help out with the project (though maybe not very advanced things at first, again, I'm still just going through the tutorial, haha). Also feel free to let me know if you think some of the above proposals wouldn't work as nicely as I imagine (maybe there's some technical details I'm not familiar with/overlooking?). Anyway, I hope you'll at least find some of these suggestions useful/helpful to the Rust community!

rustwasm / book

Some suggestions for improving "reproducibility" of tutorial #169