Skip to content
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
Closed

Explanation of mod utils is unclear #127

0xazure opened this issue Oct 23, 2018 · 1 comment

Comments

@0xazure
Copy link
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
Copy link
Member

fitzgen commented Oct 29, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants