"Guide-level" and "Reference-level" explanations to replace how we teach and detailed design sections

[carols10cents]

r? @aturon
Switch to "Guide-level" and "Reference-level" explanations

As proposed by aturon <3

These sections replace the "Detailed design" and "How do we teach this?"
sections, and switch their order.

Instead of describing how we would teach a change as a result of a
proposal, the "Guide-level explanation" section will actually attempt to
teach the reader the feature, in a lightweight way.

The guide-level explanation appears first in order to help RFC writers
keep Rust users in the front of their minds, and in order to help RFC
readers understand how an RFC will affect them sooner in the RFC. This
will hopefully make the RFC process more accessible to people who are
Rust users but not compiler or language design experts.

[est31]

I think the detailed design section is more important than the how do we teach this section, as the focus of an RFC should be on the feature and not on which sections of the rust book need changing.

[est31]

People looking to get involved in the RFC process can start at the beginning and read the summary, motivation, and how we teach this section, and hopefully have a pretty good idea what the RFC is all about. They could then choose to stop and discuss the ideas of the RFC without necessarily getting into the detailed design of the solution

The how do we teach this section most times doesn't contain anything useful for discussing the actual feature. It is discussing in which way something gets documented, while not providing any documentation itself.

[carols10cents]

I think the detailed design section is more important than the how do we teach this section, as the focus of an RFC should be on the feature and not on which sections of the rust book need changing.

Yes, however, you are someone who is currently involved in the RFC process. The purpose of this change is to help get more people involved who are currently overwhelmed by the RFC process.

The how do we teach this section most times doesn't contain anything useful for discussing the actual feature

I would like this to change and I would like this section to contain useful information :) I think it's very useful and important to think about how we incorporate new features into the way people learn and use Rust.

[carols10cents]

Relevant @wycats: https://twitter.com/wycats/status/883037436166643714

[est31]

@carols10cents what you want is a "simple explanation" section not a "how do we teach this?" section. I do support something like that but it is orthogonal to "how do we teach this" and therefore I think its better to keep the "how do we teach this" section (which concerns changes of the rust documentation) and add a completely new "simple explanation" section between motivation and detailed design.

Yes, however, you are someone who is currently involved in the RFC process. The purpose of this change is to help get more people involved who are currently overwhelmed by the RFC process.

What does this ad hominem have to do with the issue being discussed?

[shepmaster]

not on which sections of the rust book need changing.

in which way something gets documented

which concerns changes of the rust documentation

An interesting position; it feels like "how we teach this" is being distilled to "how do we update the book / API docs", while I read over half of the teaching section as being focused on broader concepts around the learnability of a concept. FWIW, I'd say that the documentation is less important than the other aspects.

While not an avid RFC reader, I feel like I've seen more RFCs than I'd like that basically say the equivalent of "we will teach this by updating the docs", which doesn't provide any value from my viewpoint.

[est31]

I've seen more RFCs than I'd like that basically say the equivalent of "we will teach this by updating the docs", which doesn't provide any value from my viewpoint.

Well most RFCs are more detailed than that and have a rough description of what document will be changed which way. This is already valuable and useful I think. The RFC that introduced this section itself has a "how do we teach this section" and it is very useful IMO.

Also I think most Rust RFCs that have been submitted haven't really introduced any new complicated changes. Most changes were just extending some already existing feature or refining it. Something like that is hard to do in a stable language in any case, you can't just remove the ownership system, nor has there been an RFC yet which introduces lazy evaluation. So I think its only expectable that only the fewest RFCs go further than that.

[Ixrec]

This proposal very strongly reminds me of the confusion I had over the second match ergonomics RFC. My full essay comment from that thread is #2005 (comment) but the part that's relevant here is:

But, I did actually read this RFC when it was first posted here, and I even read the aforementioned comments back when they were first posted, so that still leaves the question of why I had such a different impression the first few times this proposal was made. I believe it's simply because this RFC was written in a sufficiently technical and detail-oriented way that I was mildly mystified by it rather than persuaded that this is the correct design (in fact, the comments that led to this RFC had some reactions very similar to mine, such as this and this and this, which express a general confusion or uncertainty but no concrete objection). Instead of presenting a snappy high-level summary of the proposed solution such as "whenever the match value is a reference, variable bindings in the patterns are "ref-bound" by default instead of "move-bound"" which seems perfectly intuitive, it presents us with definitions of binding modes and an ASCII flowchart and various transition rules between the states in the flowchart. This rigorous presentation is great, and absolutely worth having in the RFC, but because it's the only presentation the RFC gives, I think it gave some people (myself included) a poor holistic impression of this proposal.

At the time I wrote this I think I wished the "snappy high-level summary" had been in the Summary section, but the How Do We Teach This? section would also be a great place for it.

For completeness, I do agree with @est31 that most of the time there really isn't anything interesting to say in the teaching section and with @shepmaster that most RFCs indeed do not say anything interesting there. That's part of the reason I think citing this example is useful: This particular RFC really did need a "simple explanation" in my opinion.

[est31]

Note that I don't disagree with having a snappy high level summary, in fact pushing for something like that is great, but I think its misplaced in the how do we teach this section, and either deserves its own "simple explanation" section, or should be put into the summary section.

[BurntSushi]

I do somewhat agree with the notion that "how do we teach this" is distinct from "provide an accessible high level overview." I also believe both sections are valuable. It feels like the goal of the "how do we teach this section" is to write something about the pedagogy of the thing that the RFC is proposing, where as a high level overview is about actually teaching it.

While not an avid RFC reader, I feel like I've seen more RFCs than I'd like that basically say the equivalent of "we will teach this by updating the docs", which doesn't provide any value from my viewpoint.

I'm sympathetic to this. I'm not quite sure how to fix this other than for the respective teams to prioritize this section of the RFC writing process before the RFC is approved.

[liigo]

How do we teach this?

Before we talk about this, we should have known about what 'this' is. So reading 'Detailed design' first is reasonable.

People start read ... how we teach this section, and hopefully have a pretty good idea what the RFC is all about.

When I want to have a pretty good idea about an RFC, I read 'Detailed design' directly.

People writing RFCs will perhaps work on the "How do we teach this?" section before ...

Perhaps not. Let's not talk this if you not sure.

[aturon]

So I think that we have not been using the "how do we teach this" section effectively so far; a lot of RFCs effectively just list which docs should be updated, which is not at all the point.

The idea is instead that learnability should be a first-class consideration for any feature proposal.

Now, in terms of this PR, I also had the same reaction of "I like the spirit of this, but before we talk about how to teach something, we need to say what that something is". But in chatting with @carols10cents on IRC, I now understand the intent: she really means "Please explain the feature in the way that you would teach it", i.e., "Please teach me the feature".

I think this is a great idea. In addition to focusing on teaching, it also emphasizes impact on Rust users, rather than design mechanics.

In most of my RFCs, I end up including a "The basic idea" section at the top of Detailed design, because I want to get across the basics before delving into all the small corners. I think we could sort of formalize this, along the lines of what @carols10cents is suggesting.

Concretely, what about the following?

---

Guide-level explanation

Explain the proposal as if it was already included in the language, as if you were teaching it to another Rust programmer. That generally means:

• Introducing new named concepts.
• Explaining the feature largely in terms of examples.
• Explaining how Rust programmers should think about the feature, and how it should impact the way they use Rust. It should explain the impact as concretely as possible.
• If applicable, provide sample error messages, deprecation warnings, or migration guidance.

For implementation-oriented RFCs (e.g. for compiler internals), this section should focus on how compiler contributors should think about the change, and give examples of its concrete impact. For policy RFCs, this section should provide an example-driven introduction to the policy, and explain its impact in concrete terms. And so on.

Reference-level explanation

This is the technical portion of the RFC. Explain the design in sufficient detail that:

• Its interaction with other features is clear.
• It is reasonably clear how the feature would be implemented.
• Corner cases are dissected by example.

The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.

[aturon]

cc @rust-lang/core

[aturon]

@carols10cents Want to update the PR if you're cool with my suggestion?

[carols10cents]

Yes! will do :) ❤️

[nikomatsakis]

One thing that I wanted to mention. I'm not really sure what it says about this RFC. Maybe nothing. =)

When we talk about teaching the feature, we have to keep in mind the audience. It seems clear that, in the RFC itself, the teaching is all about "teach an existing Rust programmer this new feature" -- i.e., explain it in terms of the existing concepts. But I think there is (sometimes) a need for something else, which is kind of "teach the feature as you would teach someone learning Rust from scratch".

As an example, consider the "match ergonomics" RFC. I would explain it to an existing Rust programmer by "desugaring" to ref bindings. I think that this is not how I would explain it to a "fresh" Rust programmer.

I tend to think that the "how do we teach this" section is more about "fresh Rust programmer" than about "experienced Rust programmer".

In any case, I naturally agree we should make an effort to explain the new feature in an understandable way before we dive into the technical details. Usually I too do this in the motivation section, though sometimes I merge it into the detailed design, if the details are not too complicated.

[carols10cents]

@nikomatsakis Great point! I added a line to the guide-level explanation section for RFC writers to consider whether there's a difference between teaching this to new or existing Rust programmers, wdyt?

[burdges]

In that example, there are enough developers who learn by learning roughly "what the compiler does" that the match ergonomics RFC will always need an explanation that makes clear the desugaring to ref bindings, except you'd avoid the the ref keyword and use only the & form presumably.

In general, it's true of course that fresh Rust programmers will come from a greater variety of backgrounds, which makes them a harder audience to teach to, and you don't want that albatross everywhere in an RFC.

[aturon]

@rfcbot fcp merge

[rfcbot]

Team member @aturon has proposed to merge this. The next step is review by the rest of the tagged teams:

• @alexcrichton
• @aturon
• @brson
• @carols10cents
• @erickt
• @nikomatsakis
• @nrc
• @steveklabnik
• @wycats

No concerns currently listed.

Once these reviewers reach consensus, this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[brson]

I don't have strong opinions about this and don't write many RFCs, but some observations:

• Relatively few people who this might effect (RFC authors) have left feedback, though there are some thumbs up emoji on the op.
• This format is asking me to describe the thing twice, which seems redundant. I know the directions are trying to draw a distinction, but the proper use of this format seems less clear to me.

[carols10cents]

@aturon, I've made a commit to change "Alternatives" to "Rationale and Alternatives" and adjusted the text, wdyt?
@wycats, I've added some more kinds of unresolved questions to that section, wdyt?

[aturon]

@carols10cents Changes look great!

[withoutboats]

I've written a number of RFCs & I've tried to do this with all of my "big feature" RFCs, and I'm glad to see it made a normalized part of the template. There are some RFCs which, being very small changes, these would be redundant with motivation, but those can just remove these sections I think.

[aturon]

@erickt, I took the liberty of checking your box (since you missed triage today), because I feel confident you're on board. There'll be an FCP period in case you're not :-)

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period is now complete.

[aturon]

Huzzah! This RFC has been merged! Welcome to a brave new world of RFCs.