I will look something up and will find a link to the first edition, second edition (I think there's even one I'm missing) and I come up with something like this:
Which could've been avoided by simply removing the link from ever existing in the first place; or at least disallowing it from being found in search results for user's convenience and allowing old links to redirect properly. I might sound abit ridiculous but the multiple links to the multiple versions of the multiple books are really annoying and confusing.
If this is something that's intentional, then let me know; there's probably a good reason behind leaving it in search results or if I'm being irrational please let me know as well.
Thanks
Please do this for The builder pattern as well; even though it's not linked from the main page, this ancient unfinished style guide somehow still sometimes shows up in search results above the proper one.
Because often times as many as the first three links when you do a search are actually to old versions of the book which now just tell you in some form or another "this is wrong don't look here!".
The proper solution to this is to have the old versions of the book link to the appropriate section(s) of the new book. Then the links being out of date doesn't matter, which is good, because you're never going to be able to remove or edit most of the links in the wild.
to be clear—I'd be the last to suggest to erase it, I agree keeping history is important, but removing it from the search results (maybe through robots.txt?) would be nice. The problem is that this outdated documentation appears on top of searches and most people are not looking for historical docs.
Deleting the old book is awful. Not so long ago, I tried to find a link to the as conversion rules to someone. I remember that there was a page in the old book that contained exactly that. I look for that page, only to find out that the content is deleted and replaced with a useless link. I then had to spend a few minutes trying to find where exactly this content is in the new book (note that as is not a particularly search-friendly keyword). I did not find the corresponding page in the new book at all, so I had to go and find a link to the reference instead.
My point is, don't delete the old book. Don't ban the old book from the search engine either, because there is still content that is not present (or hard to find) in the new book. Each page of the old book should have a link to the corresponding page of the new book, if any. This will allow users to find the relevant information or at least some information. The current situation is very unhelpful to users and actively destroys a good source of information.
Being distributed with old versions doesn't mean much. People won't keep the old versions installed just to read the old book. I don't even know how to open a locally installed book (is there a rustup/cargo command for that?). And that way, the book can only be useful when you already know that it contains the answers you need. When you don't know where to look, you go to Google. And when Google doesn't let you find the old book (or when the site you found refuses to show the book to you), it's the same as the book not existing.
You can visit the older docs at any time. The local docs (and they’re installed by default, you can use rustup to open them) won’t have it unless you keep an old version installed, but as long as you have an internet connection, you can always read it.
So that may technically true, but I don't think that's what people are complaining about. Consider my search this morning.
I'm documenting something and trying to include a link explaining the newtype pattern, case a reader hasn't seen it. So I go to Google and type "rust newtype" (linked so you can follow along if you want).
The first link says "1.0.0" in the URL, so I assume it's probably wrong and skip it. (It happens to be pretty accurate, but this isn't true in the general case.)
The second link is rust by example, which doesn't explain it the way I'd like.
The third link says Advanced Types and looks perfect. It gives me a "buzz off" stub page in response.
That is, someone actually went in and replaced the old book's contents with placeholder pages. I think this is what @Riateche is referring to.
It offers a link to the current version of the book. Great! I would like to link to a current version. I click on it... and I get the book's foreword.
So I go to the tiny low-contrast magnifying glass and enter "newtype". The first search result says "Advanced Types" ... promising, that's what the page I was trying to visit was called ... and so I click it and get the new Advanced Types page.
Which is... wait for it... exactly the same title, chapter, and section number as the old one. But I had to follow several links and search again to find it.
This ended happily after some legwork, but I'm currently teaching Rust to a team and we hit stuff like this daily. If the old version of the book were still online with a simple warning banner at the top of the page, I think it would be less confusing overall.
Anyway, we accepted an RFC for a version switcher over a year ago. Needs someone to implement.
I feel like I keep saying that over and over, and I’m sorry about that, but we just plain need more contributors here. The team has only shrunk over the last few years, and especially so given my recent departure. We all want great docs, but in order for that to happen, we need people to step up. There’s only so much I can do.
