Further README improvements

[JelleZijlstra]

• Move the verbiage about fragility to the CONTRIBUTING document
  as it's not relevant to users
• Mention that we also provide pyi-specific checks
• Use double quotes for code strings

[JelleZijlstra]

I think this should complete #68.

[AlexWaygood]

Just one comment, otherwise looks great to me.

I wonder if the "authors" section could also be updated? You and Łukasz obviously deserve special credit, having put far more effort into the package than anybody else — but at the moment, I think it gives the impression that you and Łukasz are the sole maintainers 🙂

Perhaps "created by Łukasz and Jelle, and now maintained by [list of maintainers]"?

[AlexWaygood]

This section is really nice, but I think I'd call it "Roadmap for development", or something similar, and then just have a bullet-point list introduced with "here are some of the changes we'd like to see happen"

[JelleZijlstra]

I feel like a bullet-point list with more specifics would just duplicate the issue tracker though. I want to avoid adding something that inevitably gets out of date.

[AlexWaygood]

Okay, then let's just create issues for these two items, and use this section to point people towards the issue tracker.

[JelleZijlstra]

Well, I think these two don't really merit issues. The first is a declaration of policy, and we already have issues for the various specific cases. The second is more of a future risk that doesn't necessarily produce an actionable issue.

[AlexWaygood]

If the second doesn't translate to an actionable issue, then I don't really think it belongs in README or CONTRIBUTING -- maybe we should just delete it?

[JelleZijlstra]

Yes, we should update the authors section, but I'd like to keep that separate because it requires confirmation from each maintainer about how they'd like to be credited. I don't think I need special credit; Łukasz set up the framework and I just added a few specific checks.

[AlexWaygood]

Yes, we should update the authors section, but I'd like to keep that separate because it requires confirmation from each maintainer about how they'd like to be credited. I don't think I need special credit; Łukasz set up the framework and I just added a few specific checks.

Sure.

[AlexWaygood]

How about we keep the stuff about incompatibility with other plugins in the README, but rephrase it so that it sounds less like a TODO for maintainers and more of a warning for users?

[Akuli]

That would be awesome :)

[JelleZijlstra]

Thanks for the reviews! I now dropped the note about future changes since it doesn't really add much over the issue tracker, and also dropped the note about the brittleness of the forward references stuff because it hasn't been an issue in the years since this package was created. Instead I added a note about compatibility with other plugins that produce inappropriate errors on pyi files, which has been a real issue.