Make the detailed design terse by separating examples #60
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.