RFCs should be written formally (most specifically, let’s ban first person pronouns)

[chris-morgan]

Take for example this snippet from https://github.com/rust-lang/rfcs/blob/7443c30a25b7ddc10a36ee3c3344596cb60ed549/active/0003-opt-in-builtin-traits.md#implementation-plan:

Here is a loose implementation plan that @flaper87 and I worked out.

Who is the first person here? Sure, I can look it up, but for these RFCs an informal writing style is undesirable.

Can we please mandate a formal writing style, or at the very least ban first person writing?

[asb]

An informal writing style seems reasonable during the feedback and
development stage of the RFC, though I agree the language should be
tightened up and formalised before being accepted+merged.

On 1 May 2014 10:12, Chris Morgan notifications@github.com wrote:

Take for example this snippet from
https://github.com/rust-lang/rfcs/blob/7443c30a25b7ddc10a36ee3c3344596cb60ed549/active/0003-opt-in-builtin-traits.md#implementation-plan
:

Here is a loose implementation plan that @flaper87https://github.com/flaper87and I worked out.

Who is the first person here? Sure, I can look it up, but for these RFCs
an informal writing style is undesirable.

Can we please mandate a formal writing style, or at the very least ban
first person writing?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/61
.

[brson]

If we credited authors on RFCs it would at least make it obvious who "I" is.

[louy2]

As long as the spec is clear, I think it doesn't matter a lot. If we are gonna do this, I think we should eliminate all pronouns and only mention the contributors at the start of the document. Where to put this guideline and make it visible?

[nagisa]

Template, which is pretty much what everybody bases their submissions
anyway. What about the old RFCs though?
On Jun 28, 2016 1:50 PM, "Yufan Lou" notifications@github.com wrote:

As long as the spec is clear, I think it doesn't matter a lot. If we are
gonna do this, I think we should eliminate all pronouns and only mention
the contributors at the start of the document. Where to put this guideline
and make it visible?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#61 (comment), or mute
the thread
https://github.com/notifications/unsubscribe/AApc0jT-W09OIYEpxD9Jnwn4tAg4vg55ks5qQPyNgaJpZM4B3FBS
.

[louy2]

What about the old RFCs though?

What about IETF style deprecation? Publish formalised ones to replace old ones. Deprecated ones are updated to point to the updated ones, and vice versa.

[strega-nil]

@louy2 "if the spec is clear"

Sure, but people (mostly me right now) have to write the spec, and it's made far more difficult when RFCs are merged with incomplete and informal language.

[louy2]

In addition, do we have something like RFC2119 yet?

[strega-nil]

@louy2 no. It's kinda... do whatever feels right, right now.

[strega-nil]

Three examples of (first-draft) RFCs:

https://github.com/rust-lang/rfcs/blob/27c33a354e42172918e9b19e78dd30a8e109433c/text/0000-pi-types.md

https://github.com/rust-lang/rfcs/blob/174e37c1e210acb8954f7357ce46529bc7f581c8/text/0000-uisize.md

https://github.com/ashleygwilliams/rfcs/blob/76c59969265223815b14fb83bccdfd5adc285f6c/text/0000-assert_ne.md

(note: I'm not saying any of these are bad, just pointing out the difference in how they're layed out)

It's unclear what an RFC should be. Should it be something everyone can understand? Should it be implementation details? Should it be written in a mathematical proving language?

[louy2]

@ubsan One thing in common: Drawbacks sections are short. But that's a digression and is probably not really related to form.

---

For reference, PEP 1 is a pretty nice guideline, but I already feel that it's a bit of a burden to read before submitting my new idea.

Ultimately, what do we want the RFCs be? Right now our RFCs seem to be at an earlier point in the discussion than others, say PEP or IETF RFC. Quote PEP 1:

Vetting an idea publicly before going as far as writing a PEP is meant to save the potential author time.

Our RFC seems to be the start of "vetting an idea publicly" instead of the result of it. Or as well as.

The enforcement better not interrupt discussion on topic. Discussion is on as soon as the RFC pull request is submitted, so that leaves enforcement to after discussion. I think a formalization before the FCP is a good timing. The RFC needs to incorporate the result of previous discussion anyway, and a formalized language can hopefully make the idea clearer for a better FCP.

As a start maybe it can be required that an RFC only enters FCP after its formalization, naturally placing the work on the creator. Help from the community is welcome always.

---

That was such a flow... but I forgot we can also use the pull request template to enforce structure beforehand.

As a real start, add an "Authors" field to the template.

[withoutboats]

I don't think that Rust is at a place where it would benefit from 2119 style MUST and such. They clarify when multiple parties are all interpreting the text carefully and need to reach the same conclusion, but for the kinds of readings we are doing, they mostly just make the text less accessible.

It seems like mildly bad form to use the first person in the text of an RFC, but not terrible (does it matter who "I" refers to?).

I haven't found RFCs to be too informal so far; incomplete or inaccessible in other ways, perhaps, but informality hasn't been an issue to me.

[Centril]

Triage: @chris-morgan do you intend to make this an RFC? If not, please close this.

[nagisa]

I have found that such “bans” or “requirements” hardly work anyway unless there is infrastructure to support them. I think that implementing tooling for this is not a good use of our resources.

[Centril]

@nagisa I agree; I'll just close it (mainly since I want to reduce our ridiculous amount of issues on this repo) and someone can write up a proper proposal if they disagree.