Python Documentation, Python language improvement, and productive discussion
Hi folks, Earlier this year at the Python Language Summit, Ned Batchelder and I presented the concept of a Documentation Workgroup and a vision for the next few years: - Slidedeck https://speakerdeck.com/willingc/cpython-documentation-the-next-5-years - Blog post https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html Due to some health issues that I have had the past few months, I haven't yet set up the workgroup. It's a priority of mine for July. We will have an open call for workgroup participants. There's a lot going on in the world with COVID19 that is impacting our lives directly and indirectly. I encourage the core development community to consider how what they share about their feelings on PEP8 may impact others. Clearly, this is an issue where it's unlikely that there will be universal agreement. As you consider additional posts about PEP8, I encourage you to think about whether your post improves the Python language before hitting Send. Stay safe as we all live together in a world facing unusual constraints due to COVID19. Warmly, Carol
On Thu, 02 Jul 2020 20:41:54 -0000 "Carol Willing" <willingc@willingconsulting.com> wrote:
Earlier this year at the Python Language Summit, Ned Batchelder and I presented the concept of a Documentation Workgroup and a vision for the next few years:
- Slidedeck https://speakerdeck.com/willingc/cpython-documentation-the-next-5-years - Blog post https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html
Due to some health issues that I have had the past few months, I haven't yet set up the workgroup. It's a priority of mine for July. We will have an open call for workgroup participants.
Kudos for doing this. Having a consistent editorial direction for the documentation is a great idea. Regards Antoine.
Hi Carol, I was wondering if you've been able to set up the workgroup yet? I'd certainly be interested in participating the there's an opportunity. Stay safe Dom
On 8/5/20 10:43 AM, Dominic Davis-Foster wrote:
Hi Carol,
I was wondering if you've been able to set up the workgroup yet? I'd certainly be interested in participating the there's an opportunity.
Stay safe
Dom
Indeed, I was wondering if there were any updates - I'm also interested in participating. -- mats
I am also interested in helping with making Python's documentation more user friendly. Yuri Selivanov's rewrite of the asyncio documentation was brilliant. We need more of that. My recent contribution to Python's doc doesn't compare with Selivanov's awesome rewrite, but it involved reorganizing existing documentation. The typing module chapter in the library reference is comprehensive, and the top 1/3 of it has good narrative explanations to the core concepts. But the remaining 2/3 of the content is in a single section titled "Classes, functions, and decorators" that covers more than 70 objects, and there's no apparent ordering. With the help of Guido, I split that section in subsections, and arranged the entries within the subsections by relevance to most users—subjective, yes, but not too harmful if we made bad calls, because now there are fewer entries per subsection. Before: https://docs.python.org/3.8/library/typing.html After: https://docs.python.org/3.10/library/typing.html Cheers, Luciano On Sun, Aug 9, 2020 at 12:43 PM Mats Wichmann <mats@python.org> wrote:
On 8/5/20 10:43 AM, Dominic Davis-Foster wrote:
Hi Carol,
I was wondering if you've been able to set up the workgroup yet? I'd certainly be interested in participating the there's an opportunity.
Stay safe
Dom
Indeed, I was wondering if there were any updates - I'm also interested in participating.
-- mats _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@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/MRV5SQCC... Code of Conduct: http://python.org/psf/codeofconduct/
-- Luciano Ramalho | Author of Fluent Python (O'Reilly, 2015) | http://shop.oreilly.com/product/0636920032519.do | Technical Principal at ThoughtWorks | Twitter: @ramalhoorg
Hi folks, Thanks for the interest. I apologize for the delay in getting this workgroup started. I'm happy that there is strong interest in working on documentation and improving it for all users. I will do my best to get the workgroup charter drafted this week and then open an interest list for initial workgroup members. Luciano, I agree that rewriting asyncio docs and typing are helpful improvements and welcome your contributions to accessible and high quality docs. Warmly, Carol On Sun, Aug 9, 2020 at 9:21 AM Luciano Ramalho <luciano@ramalho.org> wrote:
I am also interested in helping with making Python's documentation more user friendly.
Yuri Selivanov's rewrite of the asyncio documentation was brilliant. We need more of that.
My recent contribution to Python's doc doesn't compare with Selivanov's awesome rewrite, but it involved reorganizing existing documentation.
The typing module chapter in the library reference is comprehensive, and the top 1/3 of it has good narrative explanations to the core concepts. But the remaining 2/3 of the content is in a single section titled "Classes, functions, and decorators" that covers more than 70 objects, and there's no apparent ordering.
With the help of Guido, I split that section in subsections, and arranged the entries within the subsections by relevance to most users—subjective, yes, but not too harmful if we made bad calls, because now there are fewer entries per subsection.
Before: https://docs.python.org/3.8/library/typing.html
After: https://docs.python.org/3.10/library/typing.html
Cheers,
Luciano
On Sun, Aug 9, 2020 at 12:43 PM Mats Wichmann <mats@python.org> wrote:
On 8/5/20 10:43 AM, Dominic Davis-Foster wrote:
Hi Carol,
I was wondering if you've been able to set up the workgroup yet? I'd
certainly be interested in participating the there's an opportunity.
Stay safe
Dom
Indeed, I was wondering if there were any updates - I'm also interested in participating.
-- mats _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@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/MRV5SQCC... Code of Conduct: http://python.org/psf/codeofconduct/
-- Luciano Ramalho | Author of Fluent Python (O'Reilly, 2015) | http://shop.oreilly.com/product/0636920032519.do | Technical Principal at ThoughtWorks | Twitter: @ramalhoorg _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@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/P6S4Q3H6... Code of Conduct: http://python.org/psf/codeofconduct/
Hey Team, Has this workgroup started yet? If not, can I help get it going, or if so, is there a mailing list or place where things are happening? Brian Curtin On Sun, Aug 9, 2020 at 12:58 Carol Willing <willingc@gmail.com> wrote:
Hi folks,
Thanks for the interest. I apologize for the delay in getting this workgroup started. I'm happy that there is strong interest in working on documentation and improving it for all users.
I will do my best to get the workgroup charter drafted this week and then open an interest list for initial workgroup members.
Luciano, I agree that rewriting asyncio docs and typing are helpful improvements and welcome your contributions to accessible and high quality docs.
Warmly,
Carol
On Sun, Aug 9, 2020 at 9:21 AM Luciano Ramalho <luciano@ramalho.org> wrote:
I am also interested in helping with making Python's documentation more user friendly.
Yuri Selivanov's rewrite of the asyncio documentation was brilliant. We need more of that.
My recent contribution to Python's doc doesn't compare with Selivanov's awesome rewrite, but it involved reorganizing existing documentation.
The typing module chapter in the library reference is comprehensive, and the top 1/3 of it has good narrative explanations to the core concepts. But the remaining 2/3 of the content is in a single section titled "Classes, functions, and decorators" that covers more than 70 objects, and there's no apparent ordering.
With the help of Guido, I split that section in subsections, and arranged the entries within the subsections by relevance to most users—subjective, yes, but not too harmful if we made bad calls, because now there are fewer entries per subsection.
Before: https://docs.python.org/3.8/library/typing.html
After: https://docs.python.org/3.10/library/typing.html
Cheers,
Luciano
On Sun, Aug 9, 2020 at 12:43 PM Mats Wichmann <mats@python.org> wrote:
On 8/5/20 10:43 AM, Dominic Davis-Foster wrote:
Hi Carol,
I was wondering if you've been able to set up the workgroup yet? I'd
certainly be interested in participating the there's an opportunity.
Stay safe
Dom
Indeed, I was wondering if there were any updates - I'm also interested in participating.
-- mats _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@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/MRV5SQCC... Code of Conduct: http://python.org/psf/codeofconduct/
-- Luciano Ramalho | Author of Fluent Python (O'Reilly, 2015) | http://shop.oreilly.com/product/0636920032519.do | Technical Principal at ThoughtWorks | Twitter: @ramalhoorg _______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@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/P6S4Q3H6... Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@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/ZTIK4R7H... Code of Conduct: http://python.org/psf/codeofconduct/
Would be good to see @Lorena and @JulienPalard from the translation WG, might be helpful Kind Regards, Abdur-Rahmaan Janhangeer https://www.github.com/Abdur-RahmaanJ Mauritius sent from gmail client on Android, that's why the signature is so ugly.
participants (8)
-
Abdur-Rahmaan Janhangeer -
Antoine Pitrou -
Brian Curtin -
Carol Willing -
Carol Willing -
Dominic Davis-Foster -
Luciano Ramalho -
Mats Wichmann