Replacing sentences for references by a Bibliography section for keywords

[dorfsmay]

In the stdlib, at the end of each keyword description, authors add a small sentence with links to reference material.
Here are the six first ones appearing in the keyword file:

rust/src/libstd/keyword_docs.rs

Line 26 in 9733b0f

/// For more information on what `as` is capable of, see the [Reference]

rust/src/libstd/keyword_docs.rs

Line 150 in 9733b0f

/// For more detail on `const`, see the [Rust Book] or the [Reference]

rust/src/libstd/keyword_docs.rs

Line 293 in 9733b0f

/// For more information, take a look at the [Rust Book] or the [Reference]

rust/src/libstd/keyword_docs.rs

Line 336 in 9733b0f

/// For more information on FFI, check the [Rust book] or the [Reference].

rust/src/libstd/keyword_docs.rs

Line 411 in 9733b0f

/// For more information on the various types of functions and how they're used, consult the [Rust

rust/src/libstd/keyword_docs.rs

Line 486 in 9733b0f

/// More details on the functionality shown can be seen at the [`IntoIterator`] docs.

Beside the fact that they are inconsistent ("for more information", "for more details", "more details on", "see", "take a look", "check", "can be seen at"), the style itself feels heavy and goes against publishing standards. References are typically listed either in a "Reference list" or a "Bibliography".
See https://intranet.birmingham.ac.uk/as/libraryservices/library/referencing/icite/harvard/referencelist.aspx.

The two advantages of adopting this style immediately obvious:

• consistent style, not only between keywords, but with sites widely used such as Wikipedia
• reduce cognitive load for athors, trying to make up a small sentence to introduce references, especially when wanting to quote more than one.

I propose that we use a "Bibliography" section and use it for bot references and additional material pertinant to the subject.

Here's an example of an existing page, in its current version:

Replacing the "For more information..." sentence with a Blbliography section:

Comments will be appreciated.

[dorfsmay]

I don't mind doing the changes in the keyword files and submit a PR. I have already started working on it to test how to do it, but don't want to go through the whole file before confirming there is appetite for this, or proposition for something similar but better.

[tesuji]

@rustbot ping @rust-lang/docs

[rustbot]

Error: Only Rust team members can ping teams.

Please let @rust-lang/release know if you're having trouble with this bot.

[Dylan-DPC-zz]

@lzutao don't worry i'm here :P

cc @rust-lang/docs @rust-lang/libs

[steveklabnik]

I like the idea of adding consistency, but there's just not enough here for a whole "bibliography" section, and we don't do this anywhere else in the docs either, which in some sense, removes consistency. I think I'd prefer standardized wording for these kinds of links.

[dorfsmay]

Does a bibliography need a minimum length? To take Wikipedia as an example again, smaller articles often have a "Reference" section with a singe reference. A standardize wording will have more words than just "Bibliography" + a (few) bullet point(s). Note that by definition, "bibliography", covers both cited reference and other material of interest (extra reading).

What would be a good standardized wording that'd also work for a small list of reference?

[GuillaumeGomez]

I like the idea as well.

[dorfsmay]

So we have 50% like/dislike.

What could be done to get more feedback on this?

@steveklabnik what standardized wording would be better than a short Biliography?

[steveklabnik]

If you search for "For more detail" vs "for more information" in our codebase, the latter is more popular by a lot. So that's what I'd use.

[hkBst]

I like the idea. I think perhaps the word "bibliography" is a bit heavy though. Wikipedia has a "See also" section for linking to other pages within the same project. Maybe "See also" is more palatable than "bibliography"?

[dorfsmay]

Is there a better place to take this discussion to get it moving forward?