3 ms·

The Rust documentation is a bit outdated: https://www.google.com/search?q=rust+tour https://www.google.com/search?q=rust+tour the 1st result is "A 30-minute I

The Rust documentation is a bit outdated: https://www.google.com/search?q=rust+tour https://www.google.com/search?q=rust+tour the 1st result is "A 30-minute Introduction to Rust". Going through it requires 4 navigations from the user to get to a valid page, everything in between is deprecated

steveklabnik 8y ago
Interesting! That page has been deprecated for something like four years... thanks for pointing this out. I've seen people mention other pages before, but never this one.
- laszlokorte 8y ago
  It's also confusing that there are: 1. A first edition that is marked as outdated [1] 2. A second editions that seems to be not outdated [2] but 3. also the book without any edition marker that differs from the second edition [3] 4. As well as the second edition for various rust versions (eg [4] or [5]) And all of them are only distinguishable via the url. I guess the book without any version or edition marker [3] is the nightly version? But I am not sure. I guess the second-edition does not differ much between the rust versions as the chapters look the same, except for bug fixes? I am not sure. As a beginner learning rust that is really confusing because I am never sure if I am reading the correct book or if there is some other version with more information. Eg why differs [6] so much from [7] when both are the "second edition"? Ok, while writing this comment I now see that [2] are only empty pages linking to [8] and that all that books and documentation are generated for each rust version. But my point still stands: When coming from the google search result page to the rust documentation there is some confusion of what I am looking at. [1]: https://doc.rust-lang.org/book/first-edition/index.html https://doc.rust-lang.org/book/first-edition/index.html [2]: https://doc.rust-lang.org/book/second-edition/index.html https://doc.rust-lang.org/book/second-edition/index.html [3]: https://doc.rust-lang.org/book/ https://doc.rust-lang.org/book/ [4]: https://doc.rust-lang.org/1.28.0/book/second-edition/foreword.html https://doc.rust-lang.org/1.28.0/book/second-edition/forewor... [5]: https://doc.rust-lang.org/1.29.0/book/second-edition/foreword.html https://doc.rust-lang.org/1.29.0/book/second-edition/forewor... [6]: https://doc.rust-lang.org/book/second-edition/appendix-04-macros.html https://doc.rust-lang.org/book/second-edition/appendix-04-ma... [7]: https://doc.rust-lang.org/1.30.0/book/second-edition/appendix-04-macros.html https://doc.rust-lang.org/1.30.0/book/second-edition/appendi... [8]: https://doc.rust-lang.org/1.30.0/book/second-edition/ https://doc.rust-lang.org/1.30.0/book/second-edition/
  - steveklabnik 8y ago
    As of Rust 1.31, there's only one version of the book, doc.rust-lang.org/book Here's a short history: I wrote the first edition myself, before Rust 1.0. Then, Carol and I started a re-write. When it was ready to be published, we cut the final draft as the "second edition", and forked off new work in what was called the "2018 edition". That's why they're so similar. However, for various reasons, this situation isn't ideal. So we've decided to only ship the "edge" version of the book, even if it may be a bit ahead of what's currently in print.
    - fhrow4484 8y ago
      Thanks for chiming in here and giving more context. I agree with other commenters about the potential confusion for beginners. The tour of rust in 30 min should probably do an automatic redirect to the doc.rust-lang.org/book I'd love it if there was something interactive like the golang tour but the book is already a great resource. Thanks for writing it
      - steveklabnik 8y ago
        You’re welcome! That’s “Rust by example”, by the way.
- sondr3 8y ago
  I'd also like to mention that getting to the documentation for anything with Rust is fairly annoying, mostly because a ton of the stuff in the book links to the first edition and getting from the first edition to the current one is really cumbersome. It'd be great if you would be redirected from the old book to the latest version instead of getting to it and only get a warning that it isn't the latest version. Especially since there's no easy way to go from the first edition chapter to the corresponding one in the latest, it's at least three-four clicks and annoys me every single time.
  - steveklabnik 8y ago
    Can you please file bugs when you see this? I'd be happy to update them to point in the right place. We have some constraints that make plain redirects really hard; we cannot run a web server or use a ton of JavaScript, for example. Maybe this situation is painful enough for community consensus to change...
    - mwcampbell 8y ago
      > we cannot run a web server or use a ton of JavaScript Just curious, why are those constraints there?
      - steveklabnik 8y ago
        The documentation is distributed locally, as static files, as well as being available on doc.rust-lang.org. This is considered a big feature. I personally would love to tell people "sorry, you have to run a basic web server, even locally" for a few reasons, but it doesn't feel socially viable at the moment, sadly :/
        mwcampbell 8y ago
        Here's one way you might be able to make the case: If you require a web server even locally, then the docs can be installed as a single file (zip archive, SQLite database, etc.). This would eliminate the overhead of lots of small files on at least one popular desktop OS, speeding up installation and updates.

steveklabnik 8y ago

Interesting! That page has been deprecated for something like four years... thanks for pointing this out. I've seen people mention other pages before, but never this one.

laszlokorte 8y ago
It's also confusing that there are: 1. A first edition that is marked as outdated [1] 2. A second editions that seems to be not outdated [2] but 3. also the book without any edition marker that differs from the second edition [3] 4. As well as the second edition for various rust versions (eg [4] or [5]) And all of them are only distinguishable via the url. I guess the book without any version or edition marker [3] is the nightly version? But I am not sure. I guess the second-edition does not differ much between the rust versions as the chapters look the same, except for bug fixes? I am not sure. As a beginner learning rust that is really confusing because I am never sure if I am reading the correct book or if there is some other version with more information. Eg why differs [6] so much from [7] when both are the "second edition"? Ok, while writing this comment I now see that [2] are only empty pages linking to [8] and that all that books and documentation are generated for each rust version. But my point still stands: When coming from the google search result page to the rust documentation there is some confusion of what I am looking at. [1]: https://doc.rust-lang.org/book/first-edition/index.html https://doc.rust-lang.org/book/first-edition/index.html [2]: https://doc.rust-lang.org/book/second-edition/index.html https://doc.rust-lang.org/book/second-edition/index.html [3]: https://doc.rust-lang.org/book/ https://doc.rust-lang.org/book/ [4]: https://doc.rust-lang.org/1.28.0/book/second-edition/foreword.html https://doc.rust-lang.org/1.28.0/book/second-edition/forewor... [5]: https://doc.rust-lang.org/1.29.0/book/second-edition/foreword.html https://doc.rust-lang.org/1.29.0/book/second-edition/forewor... [6]: https://doc.rust-lang.org/book/second-edition/appendix-04-macros.html https://doc.rust-lang.org/book/second-edition/appendix-04-ma... [7]: https://doc.rust-lang.org/1.30.0/book/second-edition/appendix-04-macros.html https://doc.rust-lang.org/1.30.0/book/second-edition/appendi... [8]: https://doc.rust-lang.org/1.30.0/book/second-edition/ https://doc.rust-lang.org/1.30.0/book/second-edition/
- steveklabnik 8y ago
  As of Rust 1.31, there's only one version of the book, doc.rust-lang.org/book Here's a short history: I wrote the first edition myself, before Rust 1.0. Then, Carol and I started a re-write. When it was ready to be published, we cut the final draft as the "second edition", and forked off new work in what was called the "2018 edition". That's why they're so similar. However, for various reasons, this situation isn't ideal. So we've decided to only ship the "edge" version of the book, even if it may be a bit ahead of what's currently in print.
  - fhrow4484 8y ago
    Thanks for chiming in here and giving more context. I agree with other commenters about the potential confusion for beginners. The tour of rust in 30 min should probably do an automatic redirect to the doc.rust-lang.org/book I'd love it if there was something interactive like the golang tour but the book is already a great resource. Thanks for writing it
    - steveklabnik 8y ago
      You’re welcome! That’s “Rust by example”, by the way.
sondr3 8y ago
I'd also like to mention that getting to the documentation for anything with Rust is fairly annoying, mostly because a ton of the stuff in the book links to the first edition and getting from the first edition to the current one is really cumbersome. It'd be great if you would be redirected from the old book to the latest version instead of getting to it and only get a warning that it isn't the latest version. Especially since there's no easy way to go from the first edition chapter to the corresponding one in the latest, it's at least three-four clicks and annoys me every single time.
- steveklabnik 8y ago
  Can you please file bugs when you see this? I'd be happy to update them to point in the right place. We have some constraints that make plain redirects really hard; we cannot run a web server or use a ton of JavaScript, for example. Maybe this situation is painful enough for community consensus to change...
  - mwcampbell 8y ago
    > we cannot run a web server or use a ton of JavaScript Just curious, why are those constraints there?
    - steveklabnik 8y ago
      The documentation is distributed locally, as static files, as well as being available on doc.rust-lang.org. This is considered a big feature. I personally would love to tell people "sorry, you have to run a basic web server, even locally" for a few reasons, but it doesn't feel socially viable at the moment, sadly :/
      - mwcampbell 8y ago
        Here's one way you might be able to make the case: If you require a web server even locally, then the docs can be installed as a single file (zip archive, SQLite database, etc.). This would eliminate the overhead of lots of small files on at least one popular desktop OS, speeding up installation and updates.