Provide an index of educational notes for compiler errors

[hborla]

I'm starting to expand coverage for educational notes in the compiler. These are longer form explanations for error messages that explain why the problem happens and show possible strategies for resolving the error. These notes ship in the toolchain as markdown files, where the base name of the markdown file is a stable identifier for the educational note. It would be great to provide an educational notes index on Swift.org.

I’m not sure how difficult it would be to automate taking the markdown files from the compiler and adding some DocC scaffolding around it to build and render at some specified Swift.org link (ideally docs.swift.org/errors or similar), but that seems like it might be a reasonable approach.

[alexandersandberg]

Great idea! It would probably make sense to consider this for the information architecture project discussions.

cc: @dempseyatgithub

[dempseyatgithub]

I agree this sounds like a useful idea. There are potential issues such as DocC content not being very searchable beyond symbols (last I checked, would love to be incorrect.)

This may work better in the nearer term as a searchable dashboard.

Is there a plan to also make these available in Xcode or other tools?

It would be great to be able to get more details about errors right in the tool that surfaces the error.

[heckj]

There's a thread with some details on goals and initial feedback at https://forums.swift.org/t/surfacing-educational-notes-for-compiler-errors/78023

It would be "trivial" to include the markdown files in DocC as article content, but that can be quirky as well. Any content presented through DocC is presented through a javascript app, which makes indexing trickier, and within a catalog the search is minimal - so it doesn't always help with find-ability. On top of that, the URLs that access the content are only partially controllable, and impacted by file name changes. (Also additional SEO markers aren't super easily included through DocC today).

I suspect we'd want any such compiler edu note links to be extremely stable, to track things like redirects and such as needed during changes to preserve this integrity as updates roll in while maintaining compatibility for older compilers.

[hborla]

I suspect we'd want any such compiler edu note links to be extremely stable, to track things like redirects and such as needed during changes to preserve this integrity as updates roll in while maintaining compatibility for older compilers.

I agree - the intention is for the educational notes links to be 100% stable across compilers starting in Swift 6.2. New educational notes can be added in new compiler versions, but educational notes that exist in older compilers need to stick around. For example, if a particular limitation is lifted, we can leave the educational note there and just add some text that says the error no longer exists in a given compiler version.