Guidelines for documenting the *why* of something

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: https://github.com/rust-lang/spec/issues/27#issuecomment-1974734900

Review the authoring guide and existing Reference conventions, then read the linked Ada rationale and the related comment in spec issue #27. Determine where guidance on documenting motivation belongs and what limits prevent excessive context. Done means the project has an agreed policy that contributors can follow.