Users are still getting confused about where is the up-to-date Rust documentation, case #23048. This is a persistent problem, that consistently keeps getting sidelined, and even smallest fixes in this area took years. Rust has invested a lot into writing great documentation and keeping it up to date, so it pains me that it doesn't follow through to deliver that to users
Add a HUGE very clear deprecation notice to all archived versions of all documentation, all old copies of books.
Edit: sadly, browser compatibility for HTTP-inserted-CSS is poor. So it will require a different technical solution ;(
I presume that there will be push-back about modifying any of the archived files, so I'm proposing adding a notice without modifying any files, only by adding an HTTP header:
Link: </outdated-notice.css>; rel=stylesheet
This trick works, because CSS can insert generated content at the top of
<body>, and CSS can be added via HTTP headers.
Other organizations mark their outdated/archived docs very clearly, e.g. https://www.w3.org/TR/webdatabase/
And PHP, despite having a huge install base with a long tail of outdated versions, doesn't even keep old docs online! There's only one latest version of the documentation, and PHP users praise it for having helpful documentation.
There's been some attempt to add a version switcher to docs that also acts as a subtle reminder that it's not the latest version, but I'm afraid that hoping this will help is only going to keep the docs in a disarray for a few more years:
- A tiny icon in a corner does a very poor job of being a deprecation notice.
- The implementation has stalled years ago.
- The current stable docs have "since" notices, so old docs aren't even that useful for the minority of users who stubbornly struggle to use outdated and unmaintained versions of Rust.