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:

https://github.com/rust-lang/rust/blob/9733b0f122db7eb7662799b164bc02b0f54cb84a/src/libstd/keyword_docs.rs#L26

https://github.com/rust-lang/rust/blob/9733b0f122db7eb7662799b164bc02b0f54cb84a/src/libstd/keyword_docs.rs#L150

https://github.com/rust-lang/rust/blob/9733b0f122db7eb7662799b164bc02b0f54cb84a/src/libstd/keyword_docs.rs#L293

https://github.com/rust-lang/rust/blob/9733b0f122db7eb7662799b164bc02b0f54cb84a/src/libstd/keyword_docs.rs#L336

https://github.com/rust-lang/rust/blob/9733b0f122db7eb7662799b164bc02b0f54cb84a/src/libstd/keyword_docs.rs#L411

https://github.com/rust-lang/rust/blob/9733b0f122db7eb7662799b164bc02b0f54cb84a/src/libstd/keyword_docs.rs#L486

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.