-
Notifications
You must be signed in to change notification settings - Fork 12.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation for new stable features can be hard to find (e.g. for associated const) #44894
Comments
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. |
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:
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:
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. |
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 |
Triage: no changes here |
This is still a widespread problem. I believe it can be quickly solved by adding
rule to the The Here's a merge of the current live
|
Track changes to robots.txt Currently `robots.txt` of doc.rust-lang.org is not part of any repo, so there's [no way to contribute any changes to it](https://internals.rust-lang.org/t/deadlock-about-fixing-outdated-documentation-links-in-search-engines/9374), such as needed for rust-lang#44894 and countless dupes of this issue. I propose adding it to this repo. I'm not in control of the infrastructure, so I can't help to automate deployment of it, but even just having the file under source control is IMHO a step forward.
Track changes to robots.txt Currently `robots.txt` of doc.rust-lang.org is not part of any repo, so there's [no way to contribute any changes to it](https://internals.rust-lang.org/t/deadlock-about-fixing-outdated-documentation-links-in-search-engines/9374), such as needed for rust-lang#44894 and countless dupes of this issue. I propose adding it to this repo. I'm not in control of the infrastructure, so I can't help to automate deployment of it, but even just having the file under source control is IMHO a step forward.
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. |
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: 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. rust-lang/rust-guidelines@138158d 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. |
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:
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:
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).
The text was updated successfully, but these errors were encountered: