Make the detailed design terse by separating examples #60
Conversation
This file contains 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
ryantm
approved these changes
Nov 17, 2019
Ericson2314
commented
Nov 17, 2019
| This is the core, normative part of the RFC. Explain the design in enough | ||
| detail for somebody familiar with the ecosystem to understand, and implement. | ||
| This should get into specifics and corner-cases. Yet, this section should also | ||
| be terse, avoiding redundancy even at the cost of clarity. |
There was a problem hiding this comment.
I might note that an example is by definition redundant, and this is a good thing! If examples state things not covered in the formal design, then we have to reason backwards on what missing design fragment is (difficult and subjective), and also decide whether the detailed design meant to include that design fragment and forgot to, or the didn't mean to include that design fragment and the example dragged in something off-topic.
|
I'll bring this up in the RFCSC meeting on Thursday! |
domenkozar
approved these changes
Nov 21, 2019
|
Thank you all for the quick decision! |
KAction
pushed a commit
to KAction/rfcs
that referenced
this pull request
Apr 13, 2024
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.
A few times I have asked people to separate examples from the core change we are deciding on, to have a terse, precise, and unambiguous normative bit that won't become more confusing when the context that makes something wordier flow is lost over time.
There is prior art for this sort of template revision:
In ghc-proposals/ghc-proposals#251 it is pointed out that the combined section both be too wordy and have too few clarifying examples. This is a good point, lest this template change seem to skewed in favor of exports and against beginners: Everyone can win when we have terser detailed designs and far more examples.
rust-lang/rfcs#2059 is not an exact match, but I think is closer in spirit given th way things worked in practice. Before that change, the "how do we teach this" section was excessively beginner-oriented, so the detailed design would still have many intermediate-oriented details. After that change, I think it was clearer that everyone can benefit from a guide / examples, and no one should feel obligated to immediately obligated to understand the reference explanation and all its ramifications on the first pass-through. This freed that section to be more terse and precise.