[Doc-SIG] Video content in the standard library documentation

[anthony shaw]

Hi

I spend a lot of time reading the standard library documentation pages and
then condensing them down into small videos as part of either commercial
instructional courses or internal training.

The problem is that all this work is isn’t much help to the PSF or the
wider community.

It’s my view that many people can sit and read the reference pages when
they really need to check function or class documentation but beginners can
find the pages stifling, with lots of new words, phrases and references to
other stdlib modules.

I was thinking of providing a set of templates and guidelines for having “5
minute overview” videos at the top of each standard library page. Videos
would be embedded in the existing docs, starting with 3.7.

Videos would first explain
- why this module exists? What problem is it solving
- core concepts and ideas
- most basic usage examples with demos
- where to find more information and other related modules

Because modules change between minor versions, videos should not be a
comprehensive guide to the module, but a starter guide for people
unfamiliar with the module.

The template, standards and guidelines for the creation of these video
clips would live in the PSF documentation domain, as well as the review
checklist and guidelines for adding them.

Because many people would end up authoring the videos, consistency would be
important, so a structured format and template is critical.

I’m happy to volunteer to help create the template and guidelines. I know
lots of teachers in the Python world who (hopefully) could start to
contribute videos as well.

Regards
Anthony Shaw
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20180504/99288862/attachment.html>