Cargo guide feedback request!

instructions.md

Cargo Guide Feedback from People New To Rust

Thank you for your time trying out the cargo guide and providing feedback!

Here are your instructions:

1. If you haven't yet, download and install Rust. It comes with cargo, so when you're done, you should be able to run cargo in your command line and see "Rust's package manager" and some usage text.
2. Go to https://carols10cents.github.io/cargo/guide.html - it's a draft of some changes I'm proposing to the cargo guide that lives on crates.io.
3. Read through the whole thing and follow along.
4. Either leave feedback as a comment here, create a gist and link me to it here or on twitter (@Carols10cents), email feedback to me (carol.nichols@gmail.com), or comment on the pull request where I'm proposing changes!

I'm most interested to know things along these lines:

• Which parts of the guide were confusing or didn't make sense?
• Are there any parts of the guide that seem out of place?
• Do you have any questions that the guide didn't answer?
• Do you now feel confident about creating your own project with cargo? Why or why not?

Did not really understand, this part:

• If you’re building a library, put Cargo.lock in your .gitignore.
• If you’re building an executable, check Cargo.lock into git.

Hi @LeMeteore!! Thank you so much for your feedback! Is the confusing part how you know whether you're building a library or an executable? Or is it confusing why you would want to ignore or check in your Cargo.lock? Or something else?

Thank you for your time!!! ❤️ ❤️ ❤️

nitpick:

If you’d like to not initialize a new git repository as well (the default), you can also pass --vcs none.

would be clearer as

This also initializes a new git repository by default. If you don't want it to do that, pass --vcs none

I like it though!

Really excellent guide!

That sounds good @MatrixFrog, I'll make that change! Thank you!!!

@hseeberger: Thank @steveklabnik! Most of the content is from him :) I'm just doing a little tidying and testing :)

@carlos10cents What does External tests go in the tests directory. mean?

Why would a rust project have external tests?

Hi Carol, here's a couple of thoughts I had while reading.

In the Project Layout section you could perhaps include an ASCII directory structure before you do the explanation, just to help make things a little clearer.

Cargo.lock: maybe add a statement about how this should not be manually edited, for extra clarity.

The following are perhaps a bit nit-picky, but well, here goes...

• Introduces conventions, making working with Rust projects easier.
• Introduces conventions, to make working with Rust projects easier.

Cargo.toml is a manifest file. In the manifest, we can specify...
Cargo.toml is a manifest file in which we can specify...

Why would a rust project have external tests?

@mrageh Yeah, I think a better word would be "integration" rather than "external", meaning tests that exercise multiple files' worth of code as opposed to the unit tests that live in each file. Would saying integration instead clear that sentence up? Thank you for your feedback!!!

In the Project Layout section you could perhaps include an ASCII directory structure before you do the explanation, just to help make things a little clearer.

That sounds like a good idea!

Cargo.lock: maybe add a statement about how this should not be manually edited, for extra clarity.

I thought it said this, but it just says "is maintained by Cargo". I'll add a few words about not manually editing!

The nitpicky changes look good too!! Thank you!!!

Updated the draft with these changes, please let me know if these areas still need work!! ❤️ ❤️ ❤️ https://carols10cents.github.io/cargo/guide.html

@carols10cents It is confusing why I would want to ignore or check in your Cargo.lock. And thanks a lot for this guide.