Normalization for long error codes explanations RFC

[GuillaumeGomez]

We talked about it at the first meeting of the rust doc (unofficial) team so here it is: the RFC for the error codes explanations normalization!

cc @steveklabnik

Rendered.

[Stebalien]

@GuillaumeGomez you might want to edit that title/commit message.

[GuillaumeGomez]

@Stebalien: Oh indeed, I didn't pay attention... Thanks!

[steveklabnik]

@Manishearth said 👍 on IRC.

I am generally in favor of this RFC, but I would also like to hear from the people who have contributed to these messages the most. I was going to check the issue we had for error codes, but cannot find it right now. @GuillaumeGomez , do you happen to have a link?

[alilleybrinker]

@steveklabnik, do you mean this issue?

[steveklabnik]

@AndrewBrinker yes!

So, @michaelsproul, @lifthrasiir @lfairy @ruud-v-a @nham @caipre @cactorium @pnkfelix @AlisdairO @nathankleyn @joelmccracken and anyone else, thoughts on this RFC?

@pnkfelix makes a good point in that thread that isn't addressed here, but might be nice to add: rust-lang/rust#24407 (comment)

[Manishearth]

"For example, E0109 says "..."". "spans" isn't the right word to use here.

[GuillaumeGomez]

Should error explanations include references to unstable features, that is, features that are hidden behind a feature-gate, and thus are unavailable in stable and beta channels of Rust?

I think they should since error explanations will come along with (normally) this unstable feature. But before that, they shouldn't be displayed or available for a non-nightly compiler.

[ruuda]

A few thoughts:

• Sometimes very different situations that need to be fixed in different ways can lead to the same error. How would this template handle that?
• For long code samples with a bit of boilerplate, perhaps they should not be repeated entirely if the fix is a one-liner? That would make it harder to test the examples, but it is also easier to see the which parts should be changed. Something like rustdoc’s # in examples might work.
• Should this be interpreted as a loose starting point, or will all current explanations be shoehorned into this form? I am not necessarily opposed to this, but is the current situation so bad?

Providing an unified template is needed in order to help people who would want to write ones as well as people who read them.

I can see how this helps writing new examples, but I don’t see how this will help users.

[Manishearth]

Sometimes very different situations that need to be fixed in different ways can lead to the same error. How would this template handle that?

Just mention each. We do this already. https://doc.rust-lang.org/nightly/error-index.html#E0401 is an example

For long code samples with a bit of boilerplate, perhaps they should not be repeated entirely if the fix is a one-liner? That would make it harder to test the examples, but it is also easier to see the which parts should be changed. Something like rustdoc’s # in examples might work.

we don't yet test code examples in the index. But if we did, that would be correct.

Should this be interpreted as a loose starting point, or will all current explanations be shoehorned into this form? I am not necessarily opposed to this, but is the current situation so bad?

IMO loose starting point. Current explanations follow this more or less, since I've been unofficially enforcing something close to this set of guidelines when reviewing this PRs.

[GuillaumeGomez]

Sometimes very different situations that need to be fixed in different ways can lead to the same error. How would this template handle that?

Such cases are very rare. However, I think it'll be best to consider this PR as a base to apply as much as possible and then handle exceptions "by hand".

For long code samples with a bit of boilerplate, perhaps they should not be repeated entirely if the fix is a one-liner? That would make it harder to test the examples, but it is also easier to see the which parts should be changed. Something like rustdoc’s # in examples might work.

You're supposed to provide a code example as small as possible to isolate the error and to show from where it comes.

Should this be interpreted as a loose starting point, or will all current explanations be shoehorned into this form? I am not necessarily opposed to this, but is the current situation so bad?

I think it should be used as a base. The current situation isn't that bad, but can be greatly improved.

I can see how this helps writing new examples, but I don’t see how this will help users.

We're currently trying to uniformize all rust docs as well. Just like you won't have a website which changes style between pages for consistency, we're trying to apply it here as well to not loose users.

[GuillaumeGomez]

we don't yet test code examples in the index. But if we did, that would be correct.

@Manishearth: We actually do. I added it here.

[joelmccracken]

I can see how this helps writing new examples, but I don’t see how this will help users.

A template, in a way similar to a checklist, helps ensure that an error message contains everything that it should. I like it.

I suggest that the labels for the points in the template might improve. This would make the template itself easier to read and work with:

[First point] -> [Slightly more detailed error message. 50-100 words.]
[Second point] -> [Code the exemplifies the problem. 5-10 lines.]
[Third point] -> [Why the error occurs and how it may be fixed. 100-200 words.]
[Fourth point] -> [Fixed version of the earlier example. 5-10 lines.]
[Fifth point] -> [Additional details and supplementary information]

[GuillaumeGomez]

No, I prefer avoid adding limits. Some error messages need to be really complete. If I set a word "limit", they'll focus on it and I want to avoid that.

[joelmccracken]

Sure, that makes sense. The word limit was an afterthought, anyway.

[brendanzab]

Something is messed up with the code blocks here!

[GuillaumeGomez]

I don't see anything wrong. What are you referring to?

[jbcden]

I think @bjz is referring to the fact that ""##," displays inline in the rendered markdown. I am not sure if that is intentional but it does look a little odd on the page.

[GuillaumeGomez]

Arf, I don't know how markdown works in there. I was expecting that it wouldn't "interpret" in quote block.

[AlisdairO]

👍 sounds like a great plan to me!

[nrc]

Why are the labels "first point" etc.? A more semantic label/title/guideline would make more sense to me.

I'd be keen to emphasise that the template is a guideline, rather than a requirement - good docs often need quite a lot of specialisation, and docs which are obviously forced into a template often read badly.

Having said that, +1 on the RFC overall.

[GuillaumeGomez]

Why are the labels "first point" etc.? A more semantic label/title/guideline would make more sense to me.

With what would you replace it?

I'd be keen to emphasise that the template is a guideline, rather than a requirement - good docs often need quite a lot of specialisation, and docs which are obviously forced into a template often read badly.

I wrote a lot of error code explanations, and that's the more common template I fulfilled. Of course, this is "just" a guideline and some cases can't fulfill it (this template), but they remain exceptions and have to be treated on their own (even if they remain close to this RFC).

However, I think it's preferable to have a guideline and start to write something from it and then specialize the explanation if needed (and you can do it a lot). That's what has been done unofficially like @Manishearth said and it worked well.

[gnzlbg]

@GuillaumeGomez

With what would you replace it?

Still needs some work but we can try to make obvious what each section should contain

• First point -> Error description
• Second point -> Minimal example
• Third point -> Error explanation
• Four point -> How to fix it
• Fifth point -> Supplementary information

[GuillaumeGomez]

@gnzlbg: I see, I'll update it.

[joelmccracken]

I was also trying to say this. Ignore the bits I said about the word count; the other part is label name suggestions.

[GuillaumeGomez]

Updated.

[peschkaj]

"For example, actually" can become "For example".
"not all error codes explanation" -> "not all error code's explanations"
"This RFC intends to clarify this by providing a template to follow." -> "This RFC intends to clarify long error codes by providing a template to follow".

[steveklabnik]

Okay everyone! It seems like the discussion here has largely died down, so we are moving this RFC into its final comment period! 🎊

[aturon]

Took a read through this morning, and this RFC looks great to me. Thanks @GuillaumeGomez!

[GuillaumeGomez]

Thanks for your feedback @aturon!

[brson]

lgtm

[zackmdavis]

Like @nham, I'm not enthusiastic about standardizing on the verbatim phrase "Example of erroneous code:".

[alilleybrinker]

I wonder, is erroneous a bit of a poor word choice in this context? Not everyone programming in Rust speaks/reads English as their first language, and it may be preferable to choose a simpler word for this reason.

[GuillaumeGomez]

I'm french and I don't see the problem with this word (and I don't think that I have an amazing english level).

[ticki]

I am terrible at english, and I don't see a problem neither.

[Manishearth]

How about "Sample (or example) of incorrect code:"?

[alilleybrinker]

@Manishearth, this wording sounds better to me. Also, I realize this is a minor issue. If it's really not an issue in practice (and @GuillaumeGomez and @ticki seem to think it isn't), it may not be worth a change.

[GuillaumeGomez]

We already debated about this sentence. I don't know what to add about it. I put back the url.

[steveklabnik]

Huzzah! The not-quite-real docs team, in conjunction with the core team, has decided to accept this RFC. Thank you all!

[steveklabnik]

I had to do a rebase, so #1648 closed this.