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

Improve redirects #1088

Merged
merged 5 commits into from Dec 31, 2017

Conversation

Projects
None yet
3 participants
@passcod
Copy link
Contributor

passcod commented Dec 31, 2017

(Following these tweets with @steveklabnik.)

The general idea / guiding thought is this: redirects are where many people land (right now), and we're trying to retain their attention while pointing them elsewhere. At the same time, eventually the redirects will all but disappear as links are updated.

I think the current design does this poorly.

A screenshot of the current design as of this writing.

  1. It is extremely generic. It is so generic that nowhere in the actual copy does it say where you've landed, or where you're going, in more precise terms than "The Rust Book first or second edition".
  2. Many redirect pages point people to the index, which is likely one of the least useful place to go when looking for specific information.
  3. It provides no value to people beyond two links which may or may not provide the right information, which the visitor has no way of figuring out without actually clicking on.

The fact is, there is no 1:1 correspondence between 1st-ed and 2nd-ed chapters. There are a few N:1 (1st-ed to 2nd-ed), a large number of 1:N, and indeed some 1:nowhere. So it is impossible to automatically redirect people, which is the entire problem and why these redirects exist.

Hence, this Pull Request. I applied 5 incremental modifications to every redirect page:

Replace the generic title with the title of the chapter in 1st-ed

and reword the blurb to include what was previously in the title. This makes it easier to see that one has arrived to the right place.

Always go somewhere meaningful

Unless it is the correct place to go, never link to the index of the second edition as fallback. Point instead to different books, to the reference, to the API documentation, etc.

Include the title of the link's target into its text

To make it clearer where links are going, eliminate entirely the language of "Related" or the long verbose book titles. Instead, simply prefix with "In the first/second edition" as needed, and in similar style for other resources like the reference or the Unsafe book. Additionally, include the target's title, i.e. chapter number, name, and sometimes subsection, directly to the link copy.

Add a quick summary and code sample

To improve immediate value and reduce discard-because-not-useful factor upon arriving at a page which does not contain the content you were expecting, add a small blurb taken/adapted from the newer source (except in the case of pages that do not exist at all), optionally accompanied by a code sample describing the feature (or as relevant).

Keeping in mind that due to the transitive nature of the redirects, there must be no content there that isn't available elsewhere.

Highlight the recommended path and "lowlight" the old path

Instead of placing the link to the recommended resource i.e. the second edition in second place, push it up to the top of the list. In fact, push the link to the first edition always at the bottom. To emphasise even more that's where new visitors should go, bolden the first link, and make the first-ed link smaller.

This provides a clear recommendation of where to go, without completely hiding the old resource (which would be detrimental as there is value in the first-ed still).

Result

A screenshot of a redirect page with the changes applied.

(Note that the code sample should actually be a yellow runnable syntax-highlighted Rust code block, but there is no script or means to build the redirects, so I had to do the preview by manually inserting rendered HTML into an existing page, which means it lacks the fanciness.)

passcod added some commits Dec 30, 2017

Put the chapter title as the title
And reword the blurb to include what was previously in the title.

This makes it easier to see that one has arrived to the right place:
beforehand, the only indication was through the link target for the
first edition; it was nowhere in the copy itself for most pages.
Always go somewhere
Unless it is the correct place to go, never link to the index of the
second edition as fallback. Point instead to different books, to the
reference, to the API documentation, etc.
Add the title of the link into its text
To make it clearer where links are going, eliminate entirely the
language of "Related" or the long verbose book titles. Instead, simply
prefix with "In the first/second edition" as needed, and in similar
style for other resources like the reference or the Unsafe book.

Add the target's title, i.e. chapter number, name, and sometimes
subsection, directly to the link copy.
Add blurb and code example
To improve immediate value and reduce discard-because-not-useful factor
upon arriving at a page which does not contain the content you were
expecting, add a small blurb taken/adapted from the newer source,
optionally accompanied by a code sample describing the feature.

However, due to the transitive nature of this resource, there must be no
content here that isn't available elsewhere.
Highlight recommended path and lowlight the rest
Instead of placing the link to the recommended resource i.e. the second
edition in second place, push it up to the top of the list. In fact,
push the link to the first edition always at the bottom.

To emphasise even more that's where new visitors should go, bolden the
first link, and make the first-ed link smaller.

All this as well as a slight edit and simplification of the copy is
designed to make the new and recommended resources the primary path
readers take, without hiding the old resource completely.
@steveklabnik
Copy link
Member

steveklabnik left a comment

this looks great to me. thanks a ton.

@steveklabnik steveklabnik merged commit 3368af2 into rust-lang:master Dec 31, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@carols10cents

This comment has been minimized.

Copy link
Member

carols10cents commented Dec 31, 2017

Thank you for doing this! Also just a note that the book rides the release trains, so this won't hit doc.rust-lang.org/book for a while (beta backport to get it in sooner maybe, @steveklabnik ?)

@steveklabnik

This comment has been minimized.

Copy link
Member

steveklabnik commented Jan 1, 2018

I'm thinking of sending in a PR to the book shortly after the branch so that it does appear on nightly so we can get a feel for it.

steveklabnik added a commit to steveklabnik/rust that referenced this pull request Jan 25, 2018

@steveklabnik steveklabnik referenced this pull request Jan 25, 2018

Merged

Update book #47753

steveklabnik added a commit to steveklabnik/rust that referenced this pull request Jan 26, 2018

steveklabnik added a commit to steveklabnik/rust that referenced this pull request Jan 26, 2018

steveklabnik added a commit to steveklabnik/rust that referenced this pull request Jan 30, 2018

kennytm added a commit to kennytm/rust that referenced this pull request Feb 2, 2018

Rollup merge of rust-lang#47753 - steveklabnik:update-book, r=alexcri…
…chton

Update book

This PR does two things:

1. update the book to include rust-lang/book#1088
2. update to mdbook 0.1

Both of these things are big changes, so I want to land them now, well before the next branch, so we can kick the tires.

------------------------------

Locally, I'm seeing some weirdness around the reference and this:

![image](https://user-images.githubusercontent.com/27786/35411917-8dcbb31a-01e8-11e8-8c30-0bd280d93b9d.png)

Putting this PR up so others can try and build and see if it reproduces for them.

kennytm added a commit to kennytm/rust that referenced this pull request Feb 3, 2018

Rollup merge of rust-lang#47753 - steveklabnik:update-book, r=alexcri…
…chton

Update book

This PR does two things:

1. update the book to include rust-lang/book#1088
2. update to mdbook 0.1

Both of these things are big changes, so I want to land them now, well before the next branch, so we can kick the tires.

------------------------------

Locally, I'm seeing some weirdness around the reference and this:

![image](https://user-images.githubusercontent.com/27786/35411917-8dcbb31a-01e8-11e8-8c30-0bd280d93b9d.png)

Putting this PR up so others can try and build and see if it reproduces for them.

kennytm added a commit to kennytm/rust that referenced this pull request Feb 4, 2018

Rollup merge of rust-lang#47753 - steveklabnik:update-book, r=alexcri…
…chton

Update book

This PR does two things:

1. update the book to include rust-lang/book#1088
2. update to mdbook 0.1

Both of these things are big changes, so I want to land them now, well before the next branch, so we can kick the tires.

------------------------------

Locally, I'm seeing some weirdness around the reference and this:

![image](https://user-images.githubusercontent.com/27786/35411917-8dcbb31a-01e8-11e8-8c30-0bd280d93b9d.png)

Putting this PR up so others can try and build and see if it reproduces for them.

steveklabnik added a commit to steveklabnik/rust that referenced this pull request Feb 4, 2018

kennytm added a commit to kennytm/rust that referenced this pull request Feb 5, 2018

Rollup merge of rust-lang#47753 - steveklabnik:update-book, r=alexcri…
…chton

Update book

This PR does two things:

1. update the book to include rust-lang/book#1088
2. update to mdbook 0.1

Both of these things are big changes, so I want to land them now, well before the next branch, so we can kick the tires.

------------------------------

Locally, I'm seeing some weirdness around the reference and this:

![image](https://user-images.githubusercontent.com/27786/35411917-8dcbb31a-01e8-11e8-8c30-0bd280d93b9d.png)

Putting this PR up so others can try and build and see if it reproduces for them.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment