As noted,

example-plugin

repo is horribly out of date, and also harder to follow than it needs to be. I really want to fix it, but don't have the time to Rewrite It All. What do people think about archiving what we have with a git branch, and starting over from scratch? That way we can add things back one-at-a-time. (The plugin docs already give guides for each plugin hook - this is supplemental)

I upvote anything that helps kickstart updating. A sparse but accurate example repo strikes me as better than a fleshed-out repo that squanders the person's time and trust by being confusingly outdated.

Yeah, stale documentation/examples is potentially worse than none

That's exactly what I'm thinking. Thanks! This is great, I can work on this incrementally when stuck on other projects

When my PR backlog gets emptied I can volunteer some time as well

Love that teamwork!

We duplicate the example code in both the docs and the plugin, which has proven really hard to maintain and we often had typos with the docs code since we can't check that it runs. I'm thinking of rewriting so that most code examples are in the example repo. And we'll have multiple examples per plugin hook. Thoughts?

Can you embed GitHub Gists or snippets?

Yeah, some snippets in the docs can be really useful to help illustrate a point or example. Perhaps those pages could be generated a la the ref section (from say, sphinx docs perhaps) then the code samples can be tested during doc generation.