Remove apologies about the Reference #1792
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rustbot
added
the
S-waiting-on-review
traviscross
force-pushed
the
TC/remove-apologies
branch
from
c3ed844 to
d5c72e5
Compare
|
❤️ Hear hear. Much appreciation to all the contributors to the Reference. |
Right now the Reference, in its README and introduction, contains a number of warnings and caveats that amount to apologies about the document. These have outlived their usefulness and should be removed. The Reference is the reference on Rust. It's the product of an enormous amount of careful work by many people. It's a good document, and we don't need to apologize about it. In particular, these apologies don't need to be the very first things we say about the document. We don't need to warn people off from it. Given how we frame it at the moment, a reader could reasonably think, "well, if that's all its own authors think of this document, why should I waste my time with it?", and anecdotally, this is something that I've observed people reflecting back to us. Let's stop this negative cueing. Does the Reference have bugs or omissions? Sure. It always will. So does and will our compiler. We can simply point people to our issue tracker in a note; we don't need for this to be a warning, and we don't need to elaborate. Do we need to say the Reference is non-normative? No. We treat it with all the care and respect that we would any normative document, and we have for many years. We author it in normative language, and we take care to ensure that the substance of this normative language accords with normative lang team decisions. The lang team directly FCPs changes to the Reference when those changes affect the guarantees that are made by the language. Do we need to say that our descriptions of the language are "informal"? No, not in general. We work to describe things as precisely and correctly as we can. While such statements might not be "formal" ones, neither are they "informal". Do we need to say that it's not a specification? No. What is a specification anyway? We'd have to answer that before saying that it's not one. The Reference is the Reference. That's all we need to say. The text speaks for itself. Let's remove those things that have outlived their usefulness to us.
traviscross
force-pushed
the
TC/remove-apologies
branch
from
d5c72e5 to
6e62c00
Compare
traviscross
added
S-waiting-on-team
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Right now the Reference, in its README and introduction, contains a number of warnings and caveats that amount to apologies about the document. These have outlived their usefulness and should be removed. The Reference is the reference on Rust. It's the product of an enormous amount of careful work by many people. It's a good document, and we don't need to apologize about it.
In particular, these apologies don't need to be the very first things we say about the document. We don't need to warn people off from it. Given how we frame it at the moment, a reader could reasonably think, "well, if that's all its own authors think of this document, why should I waste my time with it?", and anecdotally, this is something that I've observed people reflecting back to us.
Let's stop this negative cueing.
Does the Reference have bugs or omissions? Sure. It always will. So does and will our compiler. We can simply point people to our issue tracker in a note; we don't need for this to be a warning, and we don't need to elaborate.
Do we need to say the Reference is non-normative? No. We treat it with all the care and respect that we would any normative document, and we have for many years. We author it in normative language, and we take care to ensure that the substance of this normative language accords with normative lang team decisions. The lang team directly FCPs changes to the Reference when those changes affect the guarantees that are made by the language.
Do we need to say that our descriptions of the language are "informal"? No, not in general. We work to describe things as precisely and correctly as we can. While such statements might not be "formal" ones, neither are they "informal".
Do we need to say that it's not a specification? No. What is a specification anyway? We'd have to answer that before saying that it's not one.
The Reference is the Reference. That's all we need to say. The text speaks for itself. Let's remove those things that have outlived their usefulness to us.
cc @rust-lang/spec @rust-lang/lang