Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Improve redirects #1088
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.
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).
(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.)