RFC: Educational notes for data-race safety errors

[hborla (Holly Borla)]

@Andropov

What's the vision for educational notes? I believe no tool is rendering them at the moment

That's correct, nothing is currently consuming educational notes; there's a discussion on that topic here: Surfacing educational notes for compiler errors

@Andropov

what would be the expected format? Just slightly longer compiler messages? Or more like articles?

I envision these to be more like mini articles that provide more context about the error message and show various strategies for resolving the error. I think the most important quality is that they are actionable - programmers should understand their options for resolving an error and be able to determine which approach might be applicable in the context of their code.

@Andropov

Personally I'd love to see richer media interleaved within the notes (diagrams, flows...), even if it's all complementary and the text-only version is still self-contained. I found the diagrams massively helped to explain the topic in the Swift Concurrency WWDC talks that used them. It seems to me like concurrency in particular is a topic that is hard to explain using words only. But I don't know whether that fits the concept of educational notes.

I'd love to get started with text and code examples, but I'm definitely open to exploring different visualizations for concurrency errors. I also think visualizations would be valuable to incorporate into the migration guide articles.

@Andropov

The style of the notes in the PR is spot on I'd say. Are the individual notes added meant to be complete?

They are definitely not complete. To start, I included what I think are the most common resolutions to specific error messages; you're right that there are more ways to encounter and fix region isolation errors. I was worried about making the note too long, but I think making the note a little longer might be alright if the note has more structure so that it's easy to scan for the information you're looking for.

@Andropov

I'd love to help with this if possible, once the first concurrency-related educational notes are merged What's the best way to let others know you're working on adding an educational note to an error, as to avoid working on the same thing as someone else? Just opening a issue on GitHub? Is there any other way this is coordinated?

Thank you for offering to help! I would love to collaborate We can file a top-level GitHub issue for expanding educational notes coverage (I think one exists already that we can use), and file subtasks for specific subsets of diagnostics that we're each working on to track who is working on what. I'm also happy to organize an ad-hoc "workgroup" for tackling educational notes coverage if anybody else is interested in contributing!