Create sub sections of chapter 2 or refactor to make informations about variables more visible

[n1trux]

• I have searched open and closed issues and pull requests for duplicates, using these search terms:
  • variables
  • guessing game
  • ch02-00
• I have checked the latest main branch to see if this has already been fixed, in this file:
  • https://github.com/rust-lang/book/blob/72187f5cd0beaaa9c6f584156bcd88f921871e83/src/ch02-00-guessing-game-tutorial.md

URL to the section(s) of the book with this problem: https://doc.rust-lang.org/book/ch02-00-guessing-game-tutorial.html#storing-values-with-variables

Description of the problem: The subsections do not appear in the sidebar navigation.

If you just want to know how to declare a variable, the first search result on search engines is the Reference, which does not include the simple statement to declare a variable, you write let a = 5, where a is the name of the variable but more advanced topics:

If you search for "Variable" in the Rust Book, you get three results:

• Common Programming Concepts » Variables and Mutability » Variables and Mutability
• Understanding Ownership » What is Ownership? » Variable Scope
• Programming a Guessing Game » Storing Values with Variables

Only the last one actually includes the simple

let apples = 5;

This line creates a new variable named apples and binds it to the value 5.

And is linked in "Variables and Mutability" at the top with "As mentioned in the “Storing Values with Variables” section".

Suggested fixes:

• add subheadings of Chapter 2 to the sidebar
• make "Storing Values with Variables" the first result when you search "Variables"
• add a simple line on how to declare variables to the Reference, so it can actually be called a Reference
• restructure Chapter 2 to appear after Chapter 3 so common concepts are explained before the example
  • alternatively, refactor Chapter 2 into the "Rust by Example" book
  • which incidentally also doesn't contain information about how to declare variables

related: #2790

[meltyness]

I'm not sure I can agree since, "...this book assumes that you’re reading it in sequence from front to back..."

It's also not abundantly clear which piece of information you believe is missing from the alternative examples you can stumble into which detail let and mut since each of the three are threaded via hyperlinks.

[chriskrycho]

Thanks for the issue. I understand that you were looking for some specific information and didn't find it, and that can be frustrating, but the book is structured the way it is for a reason. The second chapter is designed to let you go from a bare minimum setup to having written an interactive Rust program start to finish, which is a really rewarding thing for someone new to a language. A couple other notes:

• For the simplest introduction, Rust by Example does cover this (here).
• The Rust Reference is not a tutorial or an introduction to the language (and in fact says as much explicitly on its first page!).
• We don’t have any control over how Google, DuckDuckGo, or any other search engine indexes and displays results.

I understand that it might be nice to have an official "cheat sheet" kind of material, but it turns out when you start building that… what you end up with is something like Rust by Example, because there is a lot of ground to cover!

I am going to go ahead and close this issue, since we are not going to be doing a radical restructuring of the content. Thanks for the feedback, regardless!