Video content in the standard library documentation
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
This is something I'd be interested in contributing to as well, if we could lock down a good template and guidelines for them. I created something similar for Scratch in a series of videos called "Scratch Blocks in 60 Seconds": https://www.youtube.com/watch?v=ZCVb_EKTwQM&list=PL0-84-yl1fUki_zQ1ouwGN8t3spCTLnpS On Fri, May 4, 2018 at 3:40 PM, anthony shaw <anthony.p.shaw@gmail.com> wrote:
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
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org https://mail.python.org/mailman/listinfo/doc-sig
Thanks Al! If you’re coming to PyCon next week I was thinking of doing a sprint on it for Monday or at least discussing it over the weekend. It’ll be difficult to get good audio of course, but I think I could write a standard specification in a day with enough people to discuss and collaborate On Sun, 6 May 2018 at 11:56 am, Al Sweigart <al@inventwithpython.com> wrote:
This is something I'd be interested in contributing to as well, if we could lock down a good template and guidelines for them. I created something similar for Scratch in a series of videos called "Scratch Blocks in 60 Seconds": https://www.youtube.com/watch?v=ZCVb_EKTwQM&list=PL0-84-yl1fUki_zQ1ouwGN8t3spCTLnpS
On Fri, May 4, 2018 at 3:40 PM, anthony shaw <anthony.p.shaw@gmail.com> wrote:
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
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org https://mail.python.org/mailman/listinfo/doc-sig
I was thinking of providing a set of templates and guidelines for having “5 minute overview” videos
I propose this guideline: - Never show the face of someone speaking. Why? It allows to: - FIX a section of the sound track without re-recording the video track (in case of a error, or to better phrase something). - Translate the audio tracks of the videos without caring about lip sync (I suspect non of us are willing to do lip sync). Why fixing is important? I know one (but won't public-shame) of a really great Python video, really high video, studio, setup quality, video editing, ... all good, but we *see* the speaker state something wrong about Python! Looks like they can't fix it (setting up the studio with the same decoration is undoable). Yes they could, should probably remove the section though. Looks like Al Sweigart got this guideline right in its scratch series if we want a good example. Best, -- Julien Palard https://mdk.fr
I definitely agree will all of Julien's points. Having a face is distracting, makes editing harder, and dealing with lighting/makeup to look good on camera is a pain. Also, the videos should be a *maximum* of 6 minutes in length. Philip Guo (creator of pythontutor.com and a CS professor at Rochester) has a great article on engagement rates for online course videos. Even with the concerns about engagement aside, short videos are easier to make and keep up to date. Something else to consider: Do we need videos? We could also consider using a webpage with one of those https://trinket.io/ in-browser interactive shells (though the PSF probably doesn't want to play favorites with any company.) -Al On Sun, May 6, 2018 at 1:25 AM, Julien Palard via Doc-SIG < doc-sig@python.org> wrote:
I was thinking of providing a set of templates and guidelines for having “5 minute overview” videos
I propose this guideline:
- Never show the face of someone speaking.
Why? It allows to:
- FIX a section of the sound track without re-recording the video track (in case of a error, or to better phrase something). - Translate the audio tracks of the videos without caring about lip sync (I suspect non of us are willing to do lip sync).
Why fixing is important?
I know one (but won't public-shame) of a really great Python video, really high video, studio, setup quality, video editing, ... all good, but we *see* the speaker state something wrong about Python! Looks like they can't fix it (setting up the studio with the same decoration is undoable). Yes they could, should probably remove the section though.
Looks like Al Sweigart got this guideline right in its scratch series if we want a good example.
Best, -- Julien Palard https://mdk.fr
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org https://mail.python.org/mailman/listinfo/doc-sig
On 7 May 2018 at 05:49, Al Sweigart <al@inventwithpython.com> wrote:
I definitely agree will all of Julien's points. Having a face is distracting, makes editing harder, and dealing with lighting/makeup to look good on camera is a pain.
Also, the videos should be a *maximum* of 6 minutes in length. Philip Guo (creator of pythontutor.com and a CS professor at Rochester) has a great article on engagement rates for online course videos. Even with the concerns about engagement aside, short videos are easier to make and keep up to date.
Something else to consider: Do we need videos? We could also consider using a webpage with one of those https://trinket.io/ in-browser interactive shells (though the PSF probably doesn't want to play favorites with any company.)
The PSF doesn't tend to view that kind of thing as playing favourites - if we need to go beyond what a company offers in their baseline freemium accounts, then the PSF staff and/or Board may be able to help arrange an in-kind sponsorship, and set up a formal relationship with the vendor accordingly (e.g. PyPI relies heavily on in-kind sponsorships, and that gets recognised on https://www.python.org/psf/sponsorship/sponsors/). If it's possible to avoid videos, while still providing screencast-style content, that would be a good thing - while video playback on the web is vastly better than it used to be Cheers, Nick. P.S. Note also that the PSF has an existing technical relationship with PythonAnywhere to power the inline interactive shell in the carousel at the top of the python.org home page (click the yellow ">_" icon if you've never seen that in action). So if folks can think of ways that relationship could potentially be pursued further to help enhance the tutorial and other documentation, that would be a discussion well worth having :) -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
participants (4)
-
Al Sweigart -
anthony shaw -
Julien Palard -
Nick Coghlan