doc (book): add "Getting Started" subsection: "Essential Terminology"

[salewski]

Reworked PR (2020-11-21)

Fixes #8854

In The Cargo Book, beef-up the glossary, and provide hyperlinks to the definitions of key terms through both the "Getting Started" and "Cargo Guide" chapters.

In addition to the links, some transitional text (two sentences) has been added to the beginning of "First Steps with Cargo", and somewhat more to "Why Cargo Exists" in the guide. The intent is cater to readers jumping into this book cold, or perhaps coming from the "Hello, Cargo!" section at the beginning of The Book. The changes assume a knowledgeable but skeptical user, so take pains to justify the reader's attention. A developer that knows very little about Rust and nothing about Cargo and can follow the text and map Cargo-specific concepts to analogues in other language ecosystems.

Within the glossary many terms are touched-up, as described in the commit message for the first patch in the series. Intra-glossary links are added between all terms.

In the "Getting Started" and "Cargo Guide" chapters, terms are linked to their glossary entries throughout, for the first mention of a term within a given section. The first time a term is seen in the chapter, the markdown syntax for italics is used. In "First Steps with Cargo", both italics and bold markdown are used, in keeping with the existing styling.

Orig PR (2020-11-12) -- obsolete

Insert short terminology cheatsheet page to explain these terms:

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

Important in these definitions is the fact that a single package is defined by
a single 'Cargo.toml' file, and that a non-workspace Cargo.toml package
contains one or more crates.

The last two terms in the list are just glossed over, as it is more important
that the user know that the terms exist, and that there are both lower-level
(module) and higher-level (workspace) concepts than the organizational units
(a package and its crates) that feature most prominently in basic cargo
builds.

With the addition of this new "Essential Terminology" page, the structure at
the beginning of The Cargo Book is:

Introduction
1. Getting Started
    1.1. Essential Terminology      <= new
    1.2. Installation
    1.3. First Steps with Cargo
2. Cargo Guide
...

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, we are providing a little cheatsheet of the
essentials at this stage. Defining the above terms gives the reader a good
foothold to map concepts they may be familiar with from other languages onto
their Rust counterparts (roughly speaking).

Closes #8854

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @alexcrichton (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[alexcrichton]

Thanks for the PR! Given the prominence of this in the documentation I'd like to consider this carefully since it has the potential to affect many newcomers. To me this seems a bit out-of-place in the documentation and has a bit of a "bolt on after the fact" kind of feeling. I think ideally we would introduce these terms and explain them as part of the natural process of learning Cargo, not necessarily introducing what we might talk about later before we get there.

Did you find the existing intro docs lacking? Are terms introduced or used without much explanation as to what they are? If so could those locations perhaps get fixed?

[salewski]

Thanks for the PR! Given the prominence of this in the documentation I'd like to consider this carefully since it has the potential to affect many newcomers. To me this seems a bit out-of-place in the documentation and has a bit of a "bolt on after the fact" kind of feeling. I think ideally we would introduce these terms and explain them as part of the natural process of learning Cargo, not necessarily introducing what we might talk about later before we get there.

Did you find the existing intro docs lacking? Are terms introduced or used without much explanation as to what they are? If so could those locations perhaps get fixed?

In general, I find the Rust documentation to be excellent, and am often impressed with the clarity with which specific topics are explained. But I do think The Cargo Book could benefit from conceptually "picking up from" where the section 1.3. ("Hello, Cargo!") leaves off in The Book, as I'll elaborate on more below.

Before I get to that, though, I'll mention that I'd like to rescind this PR in its current form.

Thanks for your comments, @alexcrichton. The process of responding to them has lead me to reconsider the "Essential Terminology" section. I agree that it does have a "bolted-on" feel, which is not the way to go.

Over the next few days I'd like to rework the PR to introduce the terms where they are first used, but point the reader to specific entries in the glossary within The Cargo Book to get the full definitions. I'll also revisit the definition pieces from my initial PR; I'll drop those bits that are redundant with the material already present in the glossary, and maybe patch-in any remaining tidbits that might enhance the existing definitions.

With that said, allow me to provide some additional context around where I see a gap in the docs.

I think the motivation can best be understood from the perspective of an experienced developer who has worked with the tooling in other language ecosystems, and wants to kick the tires on Rust. Such a user is not necessarily committed to using Rust, and may be somebody who has looked at it before and is now circling back to get a sense for how it has matured since "the last time".

Such a user will likely start with The Book, the beginning of which is structured like this:

    Introduction
    1. Getting Started
        1.1. Installation
        1.2. Hello, World!
        1.3. Hello, Cargo!
    2. Programming a Guessing Game
    ...

As likely as not, section 1.1 ("Installation") was merely skimmed or even skipped if the user was able to obtain Rust and Cargo from the system package manager (e.g., 'apt-get -u install rustc cargo').

Section 1.2 ("Hello, World!") does a good job of bootstrapping the developer on the base-level essentials by creating a source artifact by hand and compiling it with rustc. The prose talks about a "project", which from context means something like "some programming endeavor"; it is clearly not some IDE-specific term, though such tools often use the term "project" for a tool-specific concept. Other familiar terminology used in this section includes "directory", "source file", "program", and "function" (in particular, "main function").

Though it could be said that the user has compiled a binary crate, that terminology is not yet introduced. It is instead referred to only as a "program" and a "binary executable", terms familiar to the reader, without any ambiguity or loss of meaning. All good.

Section 1.3 ("Hello, Cargo!") does a good job of mapping the manually created artifacts into the conventional structure expected by Cargo and achieving the same results as the earlier steps that used rustc directly. Nice.

It also mentions the familiar term "libraries", and that the Cargo-specific term "dependencies" means (apparently) the same thing thing that it means in casual developer-to-developer conversation. No surprises there; good.

Section 1.3 does a good job of motivating the need for a tool like Cargo to manage dependencies and to make build commands the same across projects (cargo build, cargo run, etc.).

Note that 1.3 is (appropriately, IMO) still using the generic term "project". The term "package" is mentioned only in passing, and reader gets the impression that it has something to do with specifying the metadata (name, version, etc) of a project.

The "Creating a Project with Cargo" section contains the first example the user sees of the cargo new command, and the section title says that the thing being created is a "project" (not a "package").

So far, so good.

1.3 notes that the rest of the book assumes the use of Cargo, and the section ends by pointing the reader at The Cargo Book to learn more.

So the developer decides to get more comfortable with Cargo before proceeding with the rest of The Book, and heads on over to The Cargo Book.

So now the user is looking at the beginning of The Cargo Book:

    Introduction
    1. Getting Started

        1.1. Installation
        1.2. First Steps with Cargo

    2. Cargo Guide
    ...

The "Introduction" page introduces the common term "package manager", and describes what that means more specifically for Cargo. This statement keeps the user comfortable in the knowledge that experience with other language-specific package managers seems to have an analogue in the Rust ecosystem.

The "Introduction" mentions that the "Getting Started" chapter will "set up your first crate". This is the first time the user has seen the term "crate". Aside from that one mention, however, the word "crate" is not used anywhere else in the "Getting Started" chapter.

The "Introduction" also mentions that the "Cargo Guide" chapter "will give you all you need to know about how to use Cargo to develop Rust packages". This is the second time the user is seeing the term "package", but it has not yet been defined. The user may have a rough notion about its meaning, as mentioned above.

If the user peeks ahead at the first two sections of the "Cargo Guide" chapter, the word "package" is used as if the user already knows what it is. So the user thinks, "Alright, it must be defined somewhere between the Introduction and here", and goes back to the Introduction.

The curious (or skeptical) reader would be well served by peeking ahead at the glossary at this point, but may think that is "too into the weeds" at this stage. In any event, it doesn't happen.

From this point forward, the scenario is the same as noted in the "Motivation" section of the description of issue #8854, so I'll just quote it here (with the obsolete bits struck):

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).

In general, if the prose within the sections in the "Introduction", the "Getting Started" chapter, and the "Cargo Guide" chapter were to provide links into the glossary upon the first mention of a given terms on a given section page, that would both answer the user's question about what a given term means and also inform the user that "Hey, there's this great list of definitions over here (that you may have otherwise missed)". Such links would also avoid the user needing to go hunt down the terms manually. Instead of providing a new cheatsheet in the form of an "Essential Terminology" page (as this original PR did), we would be pointing the user to the existing list of definitions (no cheatsheet needed).

[salewski]

I've reworked this PR as described in my last comment and the newly updated PR description; please take a look when you can:

• The bolted-on "Essential Terminology" section is no longer present, and the information from it incorporated into the Glossary.
• The Glossary itself has been updated to link intra-glossary terms with one another. (Hopping around via the links is sometimes more effective than scrolling around.)
• The terms mentioned in the "Introduction" are now links into the Glossary.
• The "Getting Started" -> "First Steps with Cargo" section has a new into blurblet that tells the reader what to expect from that page. Though the reader may not be familiar with the terms used, the links from them into the Glossary allow quick lookup.
• The "Cargo Guide" -> "Why Cargo Exists" page explains why building with a package manager is better than without. It answers the question, "Why should I care about Cargo when I've got rustc(1) and make(1)?" It also bridges the realm of familiar terms the user can be assumed to know ("libary", "program", (maybe) "rustc", (less so) "crate") to concepts important in the realm of Cargo ("crate", "package", "package manager", "registry").
• Throughout the first two chapters ("Getting Started" and "Cargo Guide"), the first time a term is used within a section it is a link into the Glossary. The first time a term is used within a chapter the link uses markdown for italics (consistent with how italics was previously used when introducing new terms).

The idea with the last item is that new users that have already read through the "Cargo Guide" are likely to be coming back to it for reference as they work with Rust. The links into the Glossary make it easier to jump into a certain section and remind oneself of what a given term means. It also serves as a reminder that the Glossary exists, which is a nice reminder that good definitions can be had from something more authoritative than a random web search.

Any feedback much appreciated. I'm happy to rework this based on suggestions for improvements. Am also fine with just dropping it if this kind of thing just isn't wanted; just let me know. Thanks,
-Al

[ehuss]

This looks good to me. @alexcrichton did you have any concerns?

[alexcrichton]

Sorry for taking a bit long to get back to you @salewski, but everything you're mentioning and the changes here look great to me! Thanks so much for giving the docs some love, it's always very much appreciated :)

@bors: r+

[bors]

📌 Commit ab78221 has been approved by alexcrichton

[bors]

⌛ Testing commit ab78221 with merge 9991af3...

[bors]

☀️ Test successful - checks-actions
Approved by: alexcrichton
Pushing 9991af3 to master...