Update RFC template

[clarfonthey]

This is something I felt might be useful to clarify after revisiting some of the wording I've made in my own RFCs. While it is technically a trivial rewording, it does have implications that I would like to get feedback on before merging.

Specifically, the two main points of contention:

1. Right now, motivation and rationale are not adequately distinguished, and this can result in RFCs that flow a little strangely. Originally, the motivation section was edited because people were underspecifying the motivation, but now, it feels like many RFCs could benefit from splitting the motivation and rationale for better document flow.
2. Right now, a lot of RFCs just include drawbacks as "technically, it is bad to add a change" which I don't think is particularly useful. Instead, this should be explicitly listing what the proposal does to limit us in the future, e.g. what kinds of features will be impossible later due to the presence of this one. It's fair for the answer to be nothing, but this is less likely the case.

It's also worth pointing out that "why should we not do this" is, well, explicitly one of the alternatives, and so, that goes better in the alternatives section. Drawbacks seems better suited to talking about future design space limitations.

(marking as a draft mostly to indicate I'd like feedback before merging. is otherwise ready to merge)

@rustbot label not-rfc

[steffahn]

I left some comments. I also looked into previous evolution of the template and saw that @Noratrieb wrote the ## Motivation section description in #3801, so I thought it might be worth the ping :3

View changes since this review

[steffahn]

I like the idea of pointing out that rationale is different from motivation.

At the same time, with this current text, it feels like you’re just repeating the things that are already clearly explained elsewhere. Right above this, there’s already

## Motivation
Any changes to Rust should focus on solving a problem that users of Rust are having.
This section should explain this problem in detail […]

so “The motivation helps you understand what the problem is” sounds a bit repetetive.

And further down in the template, there’s already

## Rationale and alternatives
- Why is this design the best in the space of possible designs?
[…]

so “After the solution is explained, you should take care to explain why this solution is the best one, in the rationale” sounds redundant as well.

IMHO make sense to point out here that – hey, make sure not to overlook that rationale goes down there into it’s own different section¹ – if that avoids an otherwise common problem in RFCs, or at least confusion point in the writing process, but we don’t need to repeat defining what each section is about.

I think, it’s possible to even misunderstand this text as it is now: By not explicitly referring down to the “Rationale and alternatives” section, this last note about “After the solution is explained, you should …” might initially sound - to a reader of this template - like it’s listing this rationale as another thing that should be included here (in the motivation section) as well.

---

I also don’t understand the sentence “the explanation is the proposed solution”. I see the words, I’m not quite sure what they’re actually telling me. “The explanation” of what? The explanation of the problem – … – is the solution(?) The explanation of the solution – … – helps understand the problem(?) Or just: the proposed solution should be explained as well(?) Something else?

Footnotes

1. I haven’t come up with an actual/concrete formulation of what to use, sorry. ↩

[steffahn]

Is this actually true though? “Possible designs” sounds to me like “possible designs that solve the problem”. Though admittedly, the explicit framing around a problem is newer than this section.

That is not to say I’m opposed to the idea of pointing out more clearly than currently the case, that “no change” is something that should be properly compared against in this rationale section. I am just wondering if this framing works best. Some more thoughts on that:

1. It feels to me like Motivation, together with Drawbacks, might already contain all the pros and cons of the comparison between this proposal vs no change. On second thought - I guess the rationale is the place where you could make sure to argue why the benefits outweigh the drawbacks? Maybe motivation is a bit more qualitative, perhaps a bit more storytelling-esque whereas here you’re supposed to more wholistically quantify and compare? I don’t actually know the answers here, I’m trying to make more sense of the template myself now 😇

2. I think listing “no change” explicitly as one of the “other designs” can also result in some meaningless boilerplate similar to the example you gave in the OP.

   Right now, a lot of RFCs just include drawbacks as "technically, it is bad to add a change" which I don't think is particularly useful

   I could anticipate boilerplate because the sentence before this line says “what other designs have been considered […]”, which means you should kinda explain/list examples in the design space (in order to then compare with them); and you don’t really need to explicitly list “no change” as an alternative when it’s always the baseline alternative to compare against, anyway.

3. I’m also noticing that just below this line in the template comes the preexisting line of

   • What is the impact of not doing this?

   which is also relevant to the rationale of why the proposed change is better than not doing anything; and in my view fits in worse with the rest of these bullet points once “no change” is declared to be one of the “possible designs”.

[steffahn]

What I like about “why should we not do this?” is that it challenges you to give a “positive” answer. You should try your best to already collect the best arguments for why not doing this is actually better.

When it’s more like “this is the ‘drawbacks’ section; please list ‘downsides’ here” - then I might feel more motivated to minimize the amount of downsides listed since - well - downsides are a bad thing, right?

I like the idea to consider limitations to future change and I can’t find that mentioned elsewhere yet! It seems vaguely related to “future possibilities” (kinda “future non-possibilities”?) but also different.

One problem with asking this question might be that RFC authors aren’t usually required to be those people who already have in mind all the - maybe wanted - future changes that could possibly be limited by a particular proposal. Though if they do know some, that’s a great thing to already include in the RFC (and if not, it’s also not a bad idea to talk to other people in advance in order to get some ideas).