New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explanation of `mod utils` is unclear #127

Closed
0xazure opened this Issue Oct 23, 2018 · 1 comment

Comments

Projects
None yet
2 participants
@0xazure
Contributor

0xazure commented Oct 23, 2018

Where in the docs did you come across this?

Section 5.2 Hello, world!

Describe what about it does not make sense

When explaining the different files provided as part of the wasm-pack-template, the tutorial mentions:

The src/utils.rs module provides a couple included batteries that we will use later in the tutorial. We can ignore it for now.

Why does it not make sense?

The set phrase I'm used to seeing is specifically "batteries included", in that order. However, if you don't know what it means for software to have "batteries included" (particularly if you come from a background or part of the industry where this phrase is not one you have been exposed to), this explanation isn't very helpful.

Also, for myself personally, I am a big-picture learner, so this explanation doesn't advance my understanding of the purpose of mod utils or why it's included. In particular, "[...] we will use [this] later in the tutorial." isn't very helpful to me because it doesn't give me an indication of when in the tutorial I might be interested in mod utils or required to use it as part of a tutorial activity.

How could we improve it?

We could explain the use of mod utils in plain English:

The src/ustils.rs module provides common utilities to make working with Rust compiled to WebAssembly easier. We will take a look at some of these utilities in more detail later in the tutorial, so we can ignore this file for now.

I would ideally also like to see a mention of specifically when in the tutorial we will use mod utils. To slightly rephrase the above and include this indication:

The src/ustils.rs module provides common utilities to make working with Rust compiled to WebAssembly easier. We will take a look at some of these utilities in more detail later in the tutorial, such as when we look at debugging our wasm code, but we can ignore this file for now.

I'd love to get some feedback on this rephrasing, and would be very happy to contribute a PR if this new phrasing is acceptable.

@fitzgen

This comment has been minimized.

Member

fitzgen commented Oct 29, 2018

This rephrasing sounds great to me! Would merge a PR that did that rephrasing.

0xazure added a commit to 0xazure/book that referenced this issue Oct 29, 2018

provide more details about mod utils
Explain the purpose of `mod utils` in plain English, and provide links
to other parts of the tutorial relevant to the purpose of `mod utils`.

Closes rustwasm#127.

@fitzgen fitzgen closed this in #129 Oct 29, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment