Adding "outdated" notices to archived versions of documentation

tools and infrastructure
1

Foreword:

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 :frowning:

Proposal:

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/

websql obituary
websql obituary3674×310 30.5 KB

and https://docs.djangoproject.com/en/2.0/

django
django1474×96 15.8 KB

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:

  1. A tiny icon in a corner does a very poor job of being a deprecation notice.
  2. The implementation has stalled years ago.
  3. 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.
35 Likes
2

I just want to signal my explicit support for this, and also thank @kornel for constantly applying pressure to get this issue fixed.

Also, I am myself definitely one of those users who are get confused by outdated docs :slight_smile:

10 Likes
3

Sounds good to me! There are other examples like Python that do this, too.

One question is how far back would these warnings appear? Would https://doc.rust-lang.org/1.43.0/ display the warning the moment 1.44 is released? Or would it wait a while (leave the most recent N releases untouched)?

Also, I'm not too familiar with Cloudfront or S3, is this relatively easy to implement? Would this require manual work during every release?

3 Likes
4

I'm agreeing 100% with @kornel. This needs to be correct to avoid confusion among beginners.

I'm sure someone can write some code to automate that even if it isn't trivially possible. Also, a feature like this is present on so many documentation sites that it can't be that hard.

1 Like
5

This has been an observable issue since forever. In that case it was even more severe, as someone from the outside searched for terms that only showed up in older documentation, so they never really had a chance.

Though I mostly wanted to say "yes please!" and that I find the header idea very interesting!

4 Likes
6

I think it'd be fine to add a notice to all non-latest versions for simplicity. Trying to judge what is "old enough" unnecessarily complicates things. The docs people should be looking at are at /stable anyway.

3 Likes
7

I love the simple to add/hard to break solution proposed here. I am emphatically on favor of doing this, even if I wish we went further and actually had relevant links to the up to date version of the docs covering the relevant topic.

5 Likes
8

The HTTP Link header for CSS is not supported in Webkit and Blink, it therefore doesn't work in Safari & Chrome (see this example).

1 Like
9

Boo :frowning:

10

Both of the examples render the warnings for me in iOS 13 Safari and macOS Safari on Catalina (both stable Safari and technology preview)…

11

Other sites just add warnings in the HTML.

AFAIK the team responsible for docs.rust-lang.org is very strict about not doing anything manually on the server, and insists on all files coming strictly from release tarballs. That's why this has been a problem for 5 years, and it took years just to add robots.txt to the site.

3 Likes
13

I'm also on Safari on macOS Catalina and the warnings do not render for me.

14

(Disclaimer: Only a sketch, not indicating this approach works or is endorsed.)

I think we could set up a Lambda@Edge function to swap out one of the JavaScript files to serve the notice (or swap out a CSS file if linking is not needed).

When the request matches the regex

^(/[0-9.]+/search-index[0-9.]*)\.js$

we instead serve the content

// better implement this using DOM manipulation for XSS safety?
var fragment = '<script defer src="$1.orig.js"></script>' +
	'<div class="docblock" style="background:#ff0;padding:0.5em;margin-bottom:1em;text-align:center;border:3px dotted red;">' +
	'This page may not describe the current stable version of Rust. ' +
	'<a href="' + location.pathname.replace(/^\/[^/]+/, '/stable') + '">' +
	'Please click here to visit the latest documentation.</a></div>';	
var mainSect = document.getElementById('main');
mainSect.innerHTML = fragment + mainSect.innerHTML;

and when the request matches the regex

^/[0-9.]+/search-index[0-9.]*\.orig\.js$

we forward the request back to the origin server after stripping out the .orig.

5 Likes
15

The Python documentation website and the PostgreSQL documentation website both have banners at the top of every page that tell you which version of the documentation you're looking at, and they give you a one- or two-click way to jump to the same page in any version of the documentation, including for versions that are no longer supported. This is very helpful when you are writing code that needs to be compatible with a broad range of versions.

I'd like Rust to adopt this kind of banner, both for the core language documentation and for crates.

13 Likes
16

You can do this fairly simply, by just attaching an id to your link and filling in the .href = URL after parsing.

17

Hey all!

We recently ported all the configuration for doc.rust-lang.org and static.rust-lang.org to Terrafrom, and it's now publicly available in the simpleinfra repository! If any of you wants to prepare a Lambda@Edge that adds the banner feel free to send a PR, so we can try it in the staging environment!

9 Likes
18

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.