Documentation for new stable features can be hard to find (e.g. for associated const)

632f552
Opened by Robin Stocker at 2021-09-21 15:51:59

Background

I was just changing some code to use associated consts for a struct. I wasn't sure what the exact syntax was, so I was looking for the documentation about it. I remembered that it was recently stabilized, so I googled for "rust associated constants". Here's the top results:

<img width="654" alt="screen shot 2017-09-28 at 11 44 54" src="https://user-images.githubusercontent.com/16778/30945591-826dff54-a442-11e7-919a-941f594cdeff.png">

The first result looked good, but because it had "1.7.0" in the URL and it was in a "Nightly Rust" section, I wasn't sure whether this feature had changed in the time that it was stabilized, so I continued my search.

The next result was the tracking issue. I tried to find a definitive statement there as to when it was actually stabilized, but couldn't find one. Also there were no links to the documentation.

So then I went looking for the Rust 1.20 announcement post, and it had some documentation. That helped. But I was still looking for something that is not a blog post, something better to link to.

So I went back to the tracking issue and found a link to an issue to add documentation to the reference. Finally, I dug up this: https://doc.rust-lang.org/stable/reference/items.html#associated-constants That's what I wanted to find in the beginning!

Possible improvements

I think there are a couple of things that could have helped me find this quicker:

  1. The first google result (the nightly rust feature page) could be updated to have a big notice with a link to the stable docs for that feature and a mentioning in which Rust version it was stabilized. (You could make an argument that old docs should not be changed, but I think it's better to be pragmatic if that's what the first search result is.)
  2. The blog post could link to the documentation.
  3. The tracking issue description could be updated to clearly state in which stable release that feature was included and link to the documentation.

All these things would make it more likely for people to find the right documentation and not have to wonder about when a feature was stabilized.

What do you think? I'm not sure if that's something that warrants an RFC or if there are any existing checklists in place for what to do when stabilizing a feature (which we could add the above things to).

  1. There's a lot here; let's talk about it at a future doc meeting. Some of this is covered by in-progress plans, some not.

    Steve Klabnik at 2017-10-31 19:42:56

  2. We talked about this in the docs team meeting today, and a lot of discussion came out of it. Primarily, i see a couple major things going on here:

    • Rust docs have... less than optimal indexing on search engines. As mentioned in the OP, google has decided that its old index of 1.7.0 (and specifically 1.7.0, not the version at the domain root or in /stable/ or the like) is the only source of API docs that it needs to care about. This is a problem because Rust has moved a lot since then. In fact, it's exacerbated it some, because it may have indexed that page at the domain root back when it was unstable, but once it got removed in favor of a heading on a different page, the 1.7.0 docs stuck because it had its own page for it! (I just ran the search myself, and i got the 1.10.0 docs instead. Hardly an improvement.)
    • Unstable features get a lot of pages to themselves, but once they stabilize they usually get folded into existing pages, and the old pages tend to stick around. Again, things like the Unstable Book are useful, but they may exacerbate the issue some, since the pages go missing when they're stabilized, so the older archives may get priority after that. In addition, all these metadata pages don't get updated when a feature actually does get stabilized, most notably the tracking issue.

    They're fairly related, but the latter is effectively a specific instance of the former. The suggestions that were raised for this are fairly far-reaching, and specifically need to pull in more people than "just the docs team" to properly deal with it. To wit:

    • Start assembling a list of stabilized feature flags in the reference, with links to their current documentation, if any. Maybe add links to tracking issues or a quick statement on each one. The idea here is to get an index of "what was stabilized when", outside of the release notes, in a place that gets distributed alongside all the other docs.
      • The issue here is keeping it up to date. We could ask to pull it into the stabilization process, but iirc the Unstable Book is already a thorn for some developers, and modifying the stabilization process probably needs to pull in @rust-lang/core?
      • There's also the related project of putting all these docs links onto the tracking issues themselves, if possible. The tracking issues are still an important page for the feature, even when closed, and simply adding a comment to the bottom of the thread is fraught and fragile, since (1) not everyone looks there, and (2) if discussion crops back up then that link is now buried.
    • Modify metadata and/or things like robots.txt on doc.rust-lang.org to (for example) disallow indexing of anything but /stable/ and /nightly/, or something like that. The idea here is to "fix" the search results to actually point to something that's more likely to be up to date.
      • This is something that would require much more discussion as to what is necessary or even effective, what is possible or feasible with respect to modifying the uploaded docs, and of course the cooperation of (probably?) @rust-lang/infra to actually access the site and modify it.

    These are Big Projects, and especially with the impl period going on it's unlikely they'll be addressed until the new year, barring a small start on the "stabilized feature flag listing" without pulling it into any outside process. Still, the problem is real and this is what we came up with in the meeting.

    QuietMisdreavus at 2017-11-07 22:19:12

  3. Currently tagging this as low because it relies on so much other work; once we do that work, we can upgrade this.

    One last thing to add to what @QuietMisdreavus said; once we implement https://github.com/rust-lang/rfcs/blob/master/text/1826-change-doc-default-urls.md this work will be easier to do

    Steve Klabnik at 2017-11-21 20:43:11

  4. Triage: no changes here

    Steve Klabnik at 2019-01-08 20:02:17

  5. This is still a widespread problem. I believe it can be quickly solved by adding

    Disallow: /1.

    rule to the robots.txt. Stable/beta/nightly docs have their own path prefixes, so this would eliminate all "archived" version-specific docs, and wouldn't require regular updates to robots.txt.

    The robots.txt file isn't part of this repo, so I can't make a PR for it.

    Here's a merge of the current live robots.txt and the proposed change:

    User-agent: *
Disallow: /0.3/
Disallow: /0.4/
Disallow: /0.5/
Disallow: /0.6/
Disallow: /0.7/
Disallow: /0.8/
Disallow: /0.9/
Disallow: /0.10/
Disallow: /0.11.0/
Disallow: /0.12.0/
# this hides all _archived_ docs for 1.x, but doesn't hide any of the latest stable/beta/nighly, which have a different path prefix
Disallow: /1.
# these links aren't the book, but old stubs/redirects that push the real book out of search results
Disallow: /book/first-edition/
Disallow: /book/second-edition/
Disallow: /stable/book/first-edition/
Disallow: /stable/book/second-edition/
Disallow: /beta/book/first-edition/
Disallow: /beta/book/second-edition/
Disallow: /nightly/book/first-edition/
Disallow: /nightly/book/second-edition/

    Kornel at 2019-01-28 17:23:24

  6. Another thing that would probably be a good idea is for the archived docs (regardless of whether they're the first Google result) to have a header in the style of the Django docs that warns people that they're not looking at the latest docs and provides a link to them.

    ...not just as one of the options to consider, but something that's done regardless of whether other measures are taken as a defense-in-depth measure in case someone winds up there.

    Stephan Sokolow at 2019-04-12 20:35:56

  7. I'd like to add on to concerns about confusions of available docs. When looking for a Rust style guide to determine semantics for rustdoc comments, I encountered the following:

    image

    The correct doc is the first result. However, it is hosted on Github, which is not the primary location for Rust docs that I have used previously as a new Rust developer. The primary docs I've used, "The Rust Programming Language" and "Rust by Example", were hosted on rust-lang.org.

    The second result (and first result from rust-lang.org) is https://doc.rust-lang.org/1.0.0/style/. This seems to be a document that was formally deprecated in May of 2015, about 2 weeks after the release of Rust 1.0. https://github.com/rust-lang/rust-guidelines/commit/138158d1e777ecb182b6b9d76352a4dc6ccffe6e

    There is no indication on rust-lang.org about this pages deprecation or when it was last modified. Even the version number is only stored in the url.

    I feel like this is a possible stumbling point for new users, and second @ssokolow's suggestion of providing warnings when referring to outdated docs like done by docs of other languages like Python.

    Luna Hart at 2021-09-21 15:51:59