Guidelines for documenting the *why* of something

[ehuss]

I think the authoring guide should have some guidelines for mentioning why something is the way it is.

In the Reference, we have generally avoided that, but I think that is a detriment to some readers, since just specifying the behavior of something can be extremely hard to understand why it matters, or how it is relevant to a Rust programmer.
That kind of information can provide useful and interesting context. However, documenting the motivation for every aspect of the language could easily overwhelm the content and be distracting.

Graydon spoke highly of the Ada rationale (the 1979 version specifically), using it while working on Rust.

A very minor example: The type_length_limit attributes explains what it does, but not why it is there. I think it could be useful to have a note like: type_length_limit is used to prevent the compiler from hanging and to better deal with polymorphic recursion.

Regardless, I think it would be good to have a policy, as contributors sometimes include this information that we then need to tell them to remove. Guidelines could bring clarity on what we expect.

See also this comment: rust-lang/spec#27 (comment)