Ned Batchelder writes: > I feel like we are missing a key element of Riccardo's point: > "without editorial guidance." Changes are being made without > first having an agreement about what the tutorial should be.
That's really unfortunate. But there also ought to be an editorial activity, such as a "tutorial-SIG" within the docs working group (ie, informality within informality -- IMO the most formal this should get is a mailing list/discuss channel, and maybe a tracker tag) to have some visibility into whether changes serve those purposes. > Personally, I would rather the tutorial did not try to cover > everything. If something is only useful to 10% of the readers, I'd > prefer to cover it elsewhere. I'd raise that 10%, maybe as high as 50%. Or maybe that's the wrong dimension to measure, and we should aim for a tutorial that covers enough for 50% of the readers to write a program that gives them more utility than just amusement and a feeling of accomplishment. > Adding tutorial-style content throughout the rest of the reference > documentation seems a fine solution to me. That's fine if the user knows what to look for, but is it really discoverable? In general, I would think that tutorial material should be most easily discoverable on its own, and that the tutorial should link to the reference material, and the reference should link, rather than include, that tutorial. And should "tutorial" material in a reference really go beyond short examples of typical use cases? Maybe these purposes would be be better served by domain-specifici HOWTOs. Eg, HOWTO write a mail filter using the mailbox and email modules. HOWTO write a web spider using requests and aiohttp. > As a compromise, we could include full text for the 80% features in the > tutorial, and in each section, include links to "other topics" or > "advanced features" in other sections. This would leave the > front-to-back readers of the tutorial with a good 80% overview of the > language, but also let readers find the tangents that are of interest to > them. I don't know if I agree with this specific outline, but I'm definitely in agreement with the principle that we should be guided by improving discoverability. _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/4UXUNCC7YE645XG4VEJHPM25IRZXRMFA/ Code of Conduct: http://python.org/psf/codeofconduct/
