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. ↩

[joshtriplett]

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

Not all repetition is a bad thing. We don't necessarily optimize human communication, including documentation, for maximum non-redundancy. A limited amount of repetition can be a form of error-correcting code, and can help people understand things.

[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”.

[joshtriplett]

I think this change is important: people should always consider and document the null alternative. The line below of "impact of not doing this" covers this as well. But in general, people get attached to the idea of their solution, and it's worth getting people to think carefully about what would actually happen in their problem domain if we decided not to make a change.

[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).

[clarfonthey]

I have been mulling this over for a bit, and there probably is a way to word this more positively, but I guess the main thing that's important here is for folks to really think about what the limits of the change are, and whether other features are still able to be present if this change is accepted.

In a real sense, it's kind of asking the author to use their imagination and think about the most out-there features that we could be doing instead of this one, and whether they could be done in addition to this feature.

That said, there are some cases where this is a truly negative case: for example, stuff like Freeze has usually been declined on the basis that libraries would start to care about Freeze as an API stability guarantee, whereas right now they don't. In the "why shouldn't we do this" case, you can be positive: yeah, we don't need to worry about that, it's great, but in most cases I'd imagine this discusses how many other desired features could fit along with this one, to discuss the drawbacks, which is mostly positive.

Not really sure what the best wording is, here.