Hi Carl,
I think the first question to answer is, are the current mypy docs (https://mypy.readthedocs.io/en/stable/) insufficient for this purpose, and why?
There’s certainly lots of great documentation in the mypy docs; it’s often my first go-to.
They do include both tutorial-style "getting started" paths as well as reference documentation. If they are not serving this purpose, why not? Is it due to their content or structure, or just because they are framed as "the mypy docs" and not "a typed Python HOWTO", so they don't find the right audience?
Framing is an aspect. For example, the information on installing, configuring, and running mypy wouldn’t (IMHO) be appropriate for a comprehensive typing guide. There’s also the fact that it lives under the mypy banner rather than under docs.python.org for example. But I think mypy’s docs would make an excellent source for the guides I’m thinking about. You’d want to write the guide being tool agnostic as much as possible (though, pointing out where semantics or behavior may differ), and you’d want to have a section on “Type Checkers” to talk about the common tools, without diving into them too much.
If we do need to write something new, one resource I can offer is an "intro to typed Python" talk I gave at PyCon 2018: https://www.youtube.com/watch?v=pMgmKJyWKn8
I’ve become a huge fan of short videos as a way to help introduce and train developers on the tools that are available to them. I’ve been working on “the documentation problem” at work for the last year+ and there’s nothing like a good video to engage with developers, especially as they start their journey into a particular topic. A series of curated videos under the Python/PSF banner would be awesome.
Cheers, -Barry