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

doc (book): knowledge of essential terminology is assumed #8854

Closed
salewski opened this issue Nov 13, 2020 · 0 comments · Fixed by #8855
Closed

doc (book): knowledge of essential terminology is assumed #8854

salewski opened this issue Nov 13, 2020 · 0 comments · Fixed by #8855

Comments

@salewski
Copy link
Contributor

[ These notes refer to The Cargo Book, as it exists as of commit 2af662e. ]

Description

The trasition between the "Introduction" and the the "Getting Started"/"First
Steps with Cargo" page could be made more reader-friendly by explaining a
handful of essential terms before they are used in an actionable way. These
terms include:

  • package
  • crate
    • library crate
    • binary crate
  • module
  • workspace

Just knowing that these are "essential terms", knowing roughly what they mean,
and how they relate to one another sets the reader up for success with the
sections that follow.

Motivation

The current reading sequence is as follows:

  1. The "Introduction" mentions that Cargo is Rust's "package manager", and
    that it manipulates "packages" (whatever those are).

  2. The "Getting Started" index urges the user to install Cargo (and Rust)
    and to set up the user's first crate (whatever that is).

  3. The "Getting Started"/"Installation" page gets the use squared away with
    tools installation.

  4. The "Getting Started"/"First Steps with Cargo" page then dives into
    instructing the user to "start a new package with Cargo".

Up until this point, the user has not been told what a "package" or a "crate"
is. A new user just poking around Rust might wonder, "What is a package, and
why would I want one? And what does a crate have to do with it?"

The terms in the above list are all well defined elsewhere in the Rust and
Cargo documentation, but a new user encountering them for the first time
should not need to hunt them down.

Since the opening sections of the Cargo book are among the first documents a
new user is likely to encounter, it would be nice to provide a little
cheatsheet at this stage of the essentials. Defining the words in the above
list would give the reader a good foothold to map concepts they may be
familiar with from other languages onto their Rust counterparts (roughly
speaking).

Outstanding Questions

Q: Should we say "a Rust package" or "a Cargo package"?

It seems pretty clear that the concepts of a "module" and a "crate" are baked
into the Rust language, so referring to "a Rust module" or "a Rust crate"
seems appropriate. (Please correct me if that is not correct.)

It also seems pretty clear that the concepts of a "package" and a "workspace"
are higher-level constructs introduced by Cargo. And conceivably, some other
tool could come along one day and replace Cargo packages and modules with some
other organizing construct (though it would likely look pretty close to what
we have today).

With that being the case, is it more correct (or even just desirable) to refer
to "a Rust package" or to "a Cargo package"? There is an equivalent question
for "workspaces", presuming that whatever is decided for "package" will hold
for "workspace", as well.

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

Successfully merging a pull request may close this issue.

1 participant