Change the default URL of doc.rust-lang.org #1826

steveklabnik · 2016-12-22T19:13:01Z

doc.rust-lang.org should redirect to the latest stable release's documentation, not duplicate /stable.

/cc @rust-lang/docs

QuietMisdreavus · 2016-12-22T20:28:01Z

It's worth noting that this changes the effect of typing doc.rust-lang-org into a web browser. Right now, without the subfolder, it's effectively an alias for /stable, meaning "the current stable docs, regardless of version". Keeping the same effect would mean redirecting to /stable instead of /VERSION.

On the other hand, going directly to the current version's docs is good for archival purposes, if it's being linked somewhere that could be revisited after a while. It becomes apparent exactly what version of rust you're talking about. In the course of typing this comment up I realized this is probably a better trade-off.

In talking with Steve about it on IRC, though, another alternative idea came about. It might be possible to turn the root index into a listing of docs subfolders, just to say "here are links to stable/beta/nightly, and specific permalinks for all these versions individually". This index would need to be updated as part of the release process, in lieu of the current option of changing the redirect.

steveklabnik · 2016-12-22T20:31:32Z

I've added it as an alternative, but if people like the idea, I'd be okay with changing this to suggest that, frankly.

GuillaumeGomez · 2016-12-23T10:05:33Z

👍

frewsxcv · 2016-12-24T06:55:26Z

text/0000-change-doc-default-urls.md

+that's affecting other parts of the project in an adverse way.
+
+The big underlying issue here is that people tend to link to `/`, becuase it's
+what you get by defualt. By changing the default, people will link to the


Nit: "defualt"

frewsxcv · 2016-12-24T19:08:10Z

text/0000-change-doc-default-urls.md

+[design]: #detailed-design
+
+https://doc.rust-lang.org/ should issue a redirect to https://doc.rust-lang.org/RELEASE,
+where RELEASE is the latest stable release, like `1.14.0`.


One concern I have with this: This will result in more people linking to https://doc.rust-lang.org/<RELEASE> URLs. This means that more people are going to be looking at potentially outdated documentation after new releases happen. I think this should at least be mentioned in the # Drawbacks section.

The solution to this is straight-forward: an "this is old documentation pls go here for current stable" banner.

Example: outdated Django and development Django have banners at the top, and https://docs.djangoproject.com/ redirects to the current latest version, https://docs.djangoproject.com/en/1.10/.

We have historically resisted doing that because it means modifying an old release after the fact.

Use an Iframe or server side magic to avoid modifying it? I agree downloaded/released docs should be immutable.

Yes, those are possible options. This is an implementation concern, not an objection to the whole idea.

Boost hit this problem as well. http://www.boost.org/libs/regex/doc/html/index.html redirects to a version-specific url, and they needed to add the "click here for latest version" link because all the stack overflow posts, for example, were pointing to ancient documentation.

Typos

aturon · 2017-01-11T21:36:07Z

This makes a lot of sense to me; it would push people more toward stable URLs and thus enable us to change rustdoc itself more freely. 👍 from me.

ollie27 · 2017-01-11T23:00:13Z

text/0000-change-doc-default-urls.md

+
+* When we release the new book, links are going to break. This has multiple
+  ways of being addressed, and so isn't a strong motivation, but fixing this
+  issue would help out a lot.


What kind of links would break, and why?

As one example, the new book does not have the same chapters as the old book, so for example, https://doc.rust-lang.org/stable/book/conditional-compilation.html will be a dead link someday.

If that chapter is removed, an appropriate redirect should be added like we have for https://doc.rust-lang.org/guide.html.

ollie27 · 2017-01-11T23:00:32Z

text/0000-change-doc-default-urls.md

+  can lead to degenerate situations in certain crates. `libc`, one of the most
+  important crates in Rust, and included in the official docs, [had their docs
+  break](https://github.com/rust-lang/libc/pull/438) because so many extra
+  files were generated that GitHub Pages refused to serve them any more.


As of rust-lang/rust#38858 the libc docs are no longer included with the std docs.

Also libc isn't exactly special. It did hit a rather bad bug in rustdoc (rust-lang/rust#37773) which caused way too many files to be generated. The redirects simply doubled the number of files rustdoc generated but that is true of every crate.

It still affects how the crate hosts its docs, even though they're not included in the distribution.

ollie27 · 2017-01-11T23:01:10Z

I think it would be better to have everything in / redirect to /stable/ instead. This would mean that /stable/ would be the canonical URL that would be shared, posted online and hopefully what search engine would link to. It has the advantage of always being the latest stable docs which is what I believe most people actually want.

Redirecting to the version specific docs doesn't help the problem of redirects if we change the URL scheme. /std/vec/struct.Vec.html and /stable/std/vec/struct.Vec.html work now and I see no reason why they shouldn't continue to work forever.

(Side note: @steveklabnik I suggest you change the rendered link at the top of this thread to rendered. The link there at the moment is out of date.)

steveklabnik · 2017-01-11T23:01:48Z

(Side note: @steveklabnik I suggest you change the rendered link at the top of this thread to rendered. The link there at the moment is out of date.)

Given the topic of this RFC, this is pretty funny. Thanks.

steveklabnik · 2017-01-11T23:02:35Z

It has the advantage of always being the latest stable docs which is what I believe most people actually want.

They're not actually "stable", though. As in, we don't make guarantees that any documentation URL will live forever. This is the root of the problem.

ollie27 · 2017-01-11T23:06:51Z

They're not actually "stable", though. As in, we don't make guarantees that any documentation URL will live forever. This is the root of the problem.

Well lets start making such guarantees. I propose all URLs in versioned docs and anything stable in / and /stable/ should live forever.

steveklabnik · 2017-01-11T23:11:50Z

I propose all URLs in versioned docs and anything stable in / and /stable/ should live forever.

This is infeasible for / and /stable, because it means that we can never update Rustdoc URLs, we can never change section headers in any long-form documentation, we can never re-organize docs.

ollie27 · 2017-01-11T23:30:02Z

This is infeasible for / and /stable, because it means that we can never update Rustdoc URLs, we can never change section headers in any long-form documentation, we can never re-organize docs.

We can. For example rustdoc is currently generating links for two URL schemes: /std/vec/struct.Vec.html and /std/vec/Vec.t.html. Swapping which one is the redirect gives us a new URL scheme and no links break. The long-form docs require a bit of care but it's no different from any other website.

It's already too late. There is a lot of content out there linking to / and /stable/ which we can't just ignore.

If we changed / to redirect to version specific docs and changed the rustdoc URL scheme, what would happen to /std/vec/struct.Vec.html? Would it break?

steveklabnik · 2017-01-12T00:02:33Z

For example rustdoc is currently generating links for two URL schemes: /std/vec/struct.Vec.html and /std/vec/Vec.t.html.

This is exactly what caused the problem in the first place. And this still doesn't address all of the other ways in which URLs change and break.

It's already too late. There is a lot of content out there linking to / and /stable/ which we can't just ignore.

They are already going to end up breaking. This is an attempt to stem the tide. No better time to change things than the present.

If we changed / to redirect to version specific docs and changed the rustdoc URL scheme, what would happen to /std/vec/struct.Vec.html? Would it break?

I'm not sure what specifically would happen here; that depends on @brson , with what we can do.

alexcrichton · 2017-01-12T00:13:09Z

@steveklabnik this RFC looks quite good to me, thanks for writing it up! My main concern is the same as @frewsxcv's concern above about notifying readers of old documentation that they're doing just that, reading old documentation. This is definitely an existing bug, but I think an implementation of this RFC as-is would exacerbate the problem to the point that it's much higher priority than it is right now.

I'd be fine with either explicitly listing this drawback and accepting the RFC on that basis, or including a solution for the problem in the RFC. I agree that some iframe-like solution would probably work well here.

@ollie27 I disagree that we should use historical precedent to just stabilize all existing URLs. There's quite a few URLs there and I'd ideally like to remove all the old ones one day. I'd like to move over to Vec.t.html and such if possible. I think @steveklabnik's argument here provides us maximal flexibility into the future without really that much cost. With an explicit warning that "you're looking at older docs" you can easily switch to newer docs, which in most cases won't really be that much different.

brson · 2017-01-12T01:39:40Z

I agree in general. And as stated, 'change doc.rust-lang.org to redirect to the latest release instead of an alias of stable', that's fine and we can do that.

But there are a few issues raised here, and I think not all of them are solved by the proposal. For example, this doesn't address the rel=canonical issue, which is mentioned in the RFC, does it?

It also doesn't address the stable/ beta/ nightly/ paths not having stable links, though I think it is hoping that culturally we will be less inclined to use those links.

One of the fallouts from this is that the URLs used in RELEASES.md will need to change going forward. Today those link to stable/, under the assumption that stable APIs' URLs won't change. Places like that, where people are publishing URLs will need to change. That does seem like an education issue. If people continue using the stable/ URL then the goal is not accomplished. There may be other fonts of rustdoc URLs like the relnotes that need to be educated about the proper URL.

It's not clear whether just / is a redirect, or whether any URL that looks like it's part of the root doc set is redirected. The latter is harder to write rules for. So I'd vote for the former.

Other things we could do:

We could make stable/ URLs redirect to / and completely kill it.

Technically, doing this proposal means adding a step to every release to change the redirection. Today that means updating rewrite rules in an nginx proxy. As an easier alternative I might suggest we create a static site just to sit at doc.rust-lang.org/, and update that instead. But, as a doc landing page there would be a lot of functional overlap with www.rust-lang.org/documentation.html. So we could think about redirecting that to doc.rust-lang.org as well, but then we have to think about i18n. Hm...

Well, that's my thoughts for now.

brson · 2017-01-12T01:41:52Z

It's not clear whether just / is a redirect, or whether any URL that looks like it's part of the root doc set is redirected. The latter is harder to write rules for. So I'd vote for the former.

If this is what we do, then we will be breaking every existing URL to that set of docs. Which is counter to the ultimate goal of having stable doc URLs, but may be for the greater good. If we're willing to break those URLs once, then I might argue we ought to go ahead and break stable/ too.

brson · 2017-01-12T01:47:33Z

One of the fallouts from this is that the URLs used in RELEASES.md will need to change going forward. Today those link to stable/

I was totally wrong about this. They link to /, not stable/.

steveklabnik · 2017-01-13T22:10:53Z

I tossed together a very quick example of what a drop-down might look like. https://rust-docs.herokuapp.com/ and https://github.com/steveklabnik/rust-docs

it doesn't work on heroku because, well, it's loading content cross-domain, but that's fixable if we wanted to do this. It also currently doesn't support any URLs other than /, but given that this only took me a few hours total, I'd imagine if we were serious about this, we could roll this into this RFC.

steveklabnik · 2017-01-13T22:12:55Z

@brson:

But there are a few issues raised here, and I think not all of them are solved by the proposal. For example, this doesn't address the rel=canonical issue, which is mentioned in the RFC, does it?

It does because we no longer have two versions of the same docs.

It also doesn't address the stable/ beta/ nightly/ paths not having stable links, though I think it is hoping that culturally we will be less inclined to use those links.

This is just never going to be true unless we agree to never remove or change URLs, which is not possible, really.

steveklabnik · 2017-01-13T23:24:20Z

(thanks to @alexcrichton and @brson that URL should work very soon)

scottmcm · 2017-01-22T10:17:30Z

Right now the easiest link to get for result is "https://doc.rust-lang.org/std/result/". If the easiest link to get becomes "https://doc.rust-lang.org/1.14.0/std/result/", then we'll end up with 16-and-growing links to "the result documentation" instead of just 2. Is there any discoverability/searchability issue caused by that if there's no rel=canonical link from the version link to the /stable one and this is is done first?

steveklabnik · 2017-01-22T18:14:00Z

Right now the easiest link to get for result is "https://doc.rust-lang.org/std/result/".

This would be the same; it would redirect. That said...

then we'll end up with 16-and-growing links to "the result documentation" instead of just 2. Is there any discoverability/searchability issue caused by that if there's no rel=canonical link from the version link to the /stable one and this is is done first?

This is a semantic issue that's not entirely clear. That is, each releases docs are canonical for their release.

steveklabnik · 2017-02-01T15:56:32Z

doc.rust-lang.org/book will go to the bookshelf homepage

It'd go to the book's homepage; the bookshelf is broader than just the book. It incorporates the nomicon, etc.

could we redirect (or suggest trying via HTML) anything not found under /book/ to the corresponding URL that includes the last rust release number that the old book exists under?

what we currently do for this is something like https://doc.rust-lang.org/guide-ffi.html; if we went with the dynamic site for doc.rust-lang.org, we could do something more comprehensive.

aturon · 2017-04-29T04:23:00Z

This RFC has gone stale. What's the current state of play? Somebody on the doc team want to push this forward?

steveklabnik · 2017-04-29T11:36:13Z

Last I chatted with @rust-lang/core , we wanted to ship the version switcher, and due to trying to knock out the rest of the book, I haven't had the chance to implement it yet. I'm hoping to do so relatively soon, and the docs team has a much lower RFC volume than the other teams, so leaving it open doesn't really hurt us.

aturon · 2017-09-06T04:04:13Z

Ping: what's the status here?

frewsxcv · 2017-09-06T13:06:00Z

Is moving forward with this dependent on the implementation being done? I don't see any big outstanding unanswered questions for this

steveklabnik · 2017-09-06T14:37:30Z

Status is, everyone wanted to see an implementation, I haven't been able to prioritize it. That simple implementation above is still there.

steveklabnik · 2017-09-06T19:34:40Z

I am going to re-read and possibly update the text soon; maybe since this is "waiting an implementation", this is a good eRFC?

steveklabnik · 2017-09-08T18:22:01Z

@rfcbot fcp merge

I have updated the RFC to explicitly contain the version-switching language, and would like to move this to FCP.

rfcbot · 2017-09-08T18:22:02Z

Team member @steveklabnik has proposed to merge this. The next step is review by the rest of the tagged teams:

No concerns currently listed.

Once these reviewers reach consensus, this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

frewsxcv · 2017-09-08T18:24:18Z

@rfcbot reviewed

QuietMisdreavus · 2017-09-08T18:26:04Z

@rfcbot reviewed

GuillaumeGomez · 2017-09-08T20:07:33Z

@rfcbot reviewed

rfcbot · 2017-09-08T20:07:34Z

🔔 This is now entering its final comment period, as per the review above. 🔔

JonSeverinsson · 2017-09-15T00:26:38Z

As written, this RFC does not actually fix the duplication issue, it only reduces it. Currently the documentation for the latest stable release exist in three places (/..., /stable/..., and /«version_number»/...). If this RFC gets implemented it would still exist in two places. (/stable/..., and /«version_number»/...). Also note that since the target RFC seems to imply that the /... -> /«version_number»/... redirection should be updated every release, it would have to be a temporary redirection, and at least Google and Bing require a permanent redirection in order to drop a search result in favor of the redirection target, so there would still be triplicate search results.

Neither does it fix the link stability issue, it only makes it more complicated: Currently /... and /stable/... is unstable, while /«version_number»/... is stable. If this RFC gets implemented,
/stable/... would be unstable (like before), /«version_number»/... would be stable (like before), and /... would become an unstable redirection to a stable location (so linking to /... would be unstable, but linking to the page you get redirected to if you follow the unstable link would be stable), a quite confusing state of affairs...

Since no perfect solution seems possible, I would suggest simply doing a permanent redirect from /... to /stable/.... It would not change the stability of any URL, and it would at least turn triplicate search results into merely duplicate search results...

steveklabnik · 2017-09-15T15:33:30Z

Since no perfect solution seems possible, I would suggest simply doing a permanent redirect from /... to /stable/.... It would not change the stability of any URL, and it would at least turn triplicate search results into merely duplicate search results...

Yeah, this seems fine to me. Thanks!

rfcbot · 2017-09-18T20:19:31Z

The final comment period is now complete.

steveklabnik · 2017-09-18T22:08:17Z

Huzzah! The @rust-lang/docs team has decided to accept this RFC.

To track further discussion, subscribe to the tracking issue here: rust-lang/rust#44687

Change the default URL of doc.rust-lang.org

2688de4

steveklabnik added the T-doc Relevant to the documentation team, which will review and decide on the RFC. label Dec 22, 2016

Add an alternative, thanks @QuietMisdreavus! ❤️

70ddb1c

Correct typos

4942945

frewsxcv reviewed Dec 24, 2016

View reviewed changes

Merge pull request #3 from shepmaster/default-url-of-docs

9b88b46

Typos

frewsxcv mentioned this pull request Dec 30, 2016

Deduplicate doc URLs rust-lang/rust#24659

Closed

ollie27 reviewed Jan 11, 2017

View reviewed changes

aturon mentioned this pull request Jan 31, 2017

Docs team roadmap rust-lang/rust-roadmap-2017#20

Open

carols10cents mentioned this pull request Feb 12, 2017

New book links to documentation are broken rust-lang/book#441

Closed

steveklabnik mentioned this pull request Mar 20, 2017

doc.rust-lang.org - old versions of the documentation appear in Google rust-lang/rust#40677

Closed

QuietMisdreavus mentioned this pull request Jun 2, 2017

doc request: stable doc pages should link to nightly docs for nightly-only features rust-lang/rust#42380

Closed

steveklabnik mentioned this pull request Jul 21, 2017

Unlist outdated Rust pages from search engines rust-lang/rust#43385

Closed

QuietMisdreavus mentioned this pull request Jul 29, 2017

Short doc url don't mention Rust version at all rust-lang/rust#14466

Closed

QuietMisdreavus mentioned this pull request Aug 7, 2017

Rustdoc issue backlog rust-dev-tools/dev-tools-team#23

Open

update as per feedback

6380129

rfcbot added the proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. label Sep 8, 2017

rfcbot added final-comment-period Will be merged/postponed/closed in ~10 calendar days unless new substational objections are raised. and removed proposed-final-comment-period Currently awaiting signoff of all team members in order to enter the final comment period. labels Sep 8, 2017

steveklabnik mentioned this pull request Sep 18, 2017

Tracking Issue for RFC 1826: Change the default URL of doc.rust-lang.org rust-lang/rust#44687

Open

2 tasks

steveklabnik merged commit 6380129 into rust-lang:master Sep 18, 2017

Centril added the A-web-presence Marketing / web presence / PSA related proposals & ideas label Nov 23, 2018

Change the default URL of doc.rust-lang.org #1826

Change the default URL of doc.rust-lang.org #1826

Conversation

steveklabnik commented Dec 22, 2016 • edited Loading

QuietMisdreavus commented Dec 22, 2016

steveklabnik commented Dec 22, 2016

GuillaumeGomez commented Dec 23, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aturon commented Jan 11, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ollie27 commented Jan 11, 2017

steveklabnik commented Jan 11, 2017

steveklabnik commented Jan 11, 2017

ollie27 commented Jan 11, 2017

steveklabnik commented Jan 11, 2017

ollie27 commented Jan 11, 2017

steveklabnik commented Jan 12, 2017

alexcrichton commented Jan 12, 2017

brson commented Jan 12, 2017

brson commented Jan 12, 2017 • edited Loading

brson commented Jan 12, 2017

steveklabnik commented Jan 13, 2017 • edited Loading

steveklabnik commented Jan 13, 2017

steveklabnik commented Jan 13, 2017

scottmcm commented Jan 22, 2017

steveklabnik commented Jan 22, 2017 • edited Loading

steveklabnik commented Feb 1, 2017

aturon commented Apr 29, 2017

steveklabnik commented Apr 29, 2017

aturon commented Sep 6, 2017

frewsxcv commented Sep 6, 2017

steveklabnik commented Sep 6, 2017

steveklabnik commented Sep 6, 2017

steveklabnik commented Sep 8, 2017

rfcbot commented Sep 8, 2017 • edited by GuillaumeGomez Loading

frewsxcv commented Sep 8, 2017

QuietMisdreavus commented Sep 8, 2017

GuillaumeGomez commented Sep 8, 2017

rfcbot commented Sep 8, 2017

JonSeverinsson commented Sep 15, 2017

steveklabnik commented Sep 15, 2017

rfcbot commented Sep 18, 2017

steveklabnik commented Sep 18, 2017

steveklabnik commented Dec 22, 2016 •

edited

Loading

brson commented Jan 12, 2017 •

edited

Loading

steveklabnik commented Jan 13, 2017 •

edited

Loading

steveklabnik commented Jan 22, 2017 •

edited

Loading

rfcbot commented Sep 8, 2017 •

edited by GuillaumeGomez

Loading