Iteration toward Transformation of the Python Documentation
With the tremendous growth of the Python ecosystem, attracting an ever-wider audience of users with a variety of backgrounds and experience levels, it is more critical than ever that its documentation better serve the needs of its diverse array of readers. We formally introduce the Python Docs Community—the self-organized, Python Steering Council-endorsed collective working toward this goal—and provide a look at the major user-facing improvements implemented, underway and coming soon for the core documentation, devguide, PEPs and more.
Along the way, we'll share the key insights and lessons learned from our ongoing projects, and how they can help you improve the documentation of your own projects. And if this sounds like something you might want to be a part of, we'll share how you can engage with us and your fellow documentarians through our community platforms and resources.
45 minute slot preferred, in order to outline the key efforts the Python docs community has been driving forward, demo planned upcoming changes to the core Python docs and other resources that will be of significant interest to the community, and in particular share our key insights useful for other projects' documentation. However, we would adjust the outline as indicated in detail in the Outline section if only approved for a 30 minute talk.
Co-presenter Erlend E. Aasland will need to fly out in the afternoon of April 21 (specific time TBD, as he is still securing a flight), so a talk the morning of April 21 or earlier is preferred. However, is needed CAM will be equally prepared to present that section of the talk as well if the talk is scheduled at a time after Erlend is not available.
- A look inside the Docs Community (4 min)
- Presenter intro(s) and ACKs (1 min)
- History and how I got involved (1 min)
- Purpose, focus and organization (1 min)
- Docs community site, repo, discord, discourse, meetings (1 min)
- Looking back: Incremental transformation (10 min)
- CPython Docs (5 min)
- Diataxis framework to better serve users (3 min)
- Better search so users can find docs more easily (1 min)
- Moving toward more structured, complete, easy to skim API reference (0.5 min)
- Rendered previews to make contributing and reviewing quicker and easier (0.5 min)
- Devguide (2 min)
- Re-organization for easier navigation and to be more accessible for new contributors (0.75 min)
- Expanded release lifecycle info for users (and APIs) (0.75 min)
- New docs quick reference for contributors (0.5 min)
- PEPs (2 min)
- New modern theme, rendering system and user- and author-facing features (1 min)
- Per-topic indices to browse PEPs of interest (0.25 min)
- More useful links & metadata for readers wanting to know more (0.25 min)
- New API and third-party tools for jumping to and tracking PEPs (0.25 min)
- Better help for authors (0.25 min)
- Cross-cutting and more (1 min)
- SEO improvements helping users find up to date docs when searching (0.25 min)
- Also supports useful previews/integrations on other platforms (0.25 min)
- How you can do the same in your own docs (0.5 min)
- CPython Docs (5 min)
- A closer look: Insights from the
sqlite3Diataxis revamp (15 min) - Erlend- Summarize previous state of sqlite3 docs and need for revamp (2 min)
- Initial perceptions of Diataxis and plans for the changes (1 min)
- Describe the resulting Diataxification process, challenges and benefits to users (5 min)
- Started with making sure the most important functions and behaviors were clear
- Then ensuring the reference was complete, organized and accurate
- Then split into the four Diataxis sections incrementally (titles, move, content)
- Then work on the tutorial
- Finally make further improvements in How-To/Explanation
- Useful insights gained (5 min)
- Start small and take an incremental approach
- Don't be afraid to iterate as things progress
- Tutorials are hard to get right
- Having reviewers of varying experience levels helps a lot
- Focus on better serving readers first, and the organization will follow
- Additional insights and examples
- Mention other lessons learned from other aspects of the docs transformation process (2 min)
- Looking to the the future: What's next for Python docs (10 minutes)
- Overview and Demo of new proposed Python docs theme with dark theme, better navigation features and responsiveness, and cohesive with rest of ecosystem (5 min)
- Continuing Diataxis transformation incrementally (1 min)
- New tooling to extract, check, analyze, visualize and leverage structured data in code & docs, that can be used to improve both Python's and your own (2 min)
- (TBD) Other upcoming plans the docs community wants to share (2 min)
- Looking to help: How can you get involved? (1 min)
- Discourse, Discord, attend meetings, help with ongoing projects, share user feedback, contribute!
- Questions (5 min)
- A look inside the Docs Community (3 min)
- Presenter intro(s) and ACKs (1 min)
- History and how I got involved (1 min)
- Purpose, focus and organization (1 min)
- Looking back: Incremental transformation (6 min)
- CPython Docs (3 min)
- Diataxis framework to better serve users (2 min)
- Better search so users can find docs more easily (0.5 min)
- Moving toward more structured, complete, easy to skim API reference (0.25 min)
- Rendered previews to make contributing and reviewing quicker and easier (0.25 min)
- Devguide (1 min)
- Re-organization for easier navigation and to be more accessible for new contributors (0.5 min)
- Expanded release lifecycle info for users (and APIs) (0.5 min)
- PEPs (1 min)
- New modern theme, rendering system and user- and author-facing features (0.5 min)
- Per-topic indices to browse PEPs of interest (0.25 min)
- More useful links & metadata for readers wanting to know more (0.25 min)
- Cross-cutting and more (1 min)
- SEO improvements helping users find up to date docs when searching (0.25 min)
- Also supports useful previews/integrations on other platforms (0.25 min)
- How you can do the same in your own docs (0.5 min)
- CPython Docs (3 min)
- A closer look: Insights from the
sqlite3Diataxis revamp (10 min) - Erlend- Summarize previous state of sqlite3 docs and need for revamp (1 min)
- Describe the resulting Diataxification process, challenges and benefits to users (4 min)
- Started with making sure the most important functions and behaviors were clear
- Then ensuring the reference was complete, organized and accurate
- Then split into the four Diataxis sections incrementally (titles, move, content)
- Then work on the tutorial
- Finally make further improvements in How-To/Explanation
- Useful insights gained (4 min)
- Start small and take an incremental approach
- Don't be afraid to iterate as things progress
- Tutorials are hard to get right
- Having reviewers of varying experience levels helps a lot
- Focus on better serving readers first, and the organization will follow
- Additional insights and examples
- Looking to the the future: What's next for Python docs (5 minutes)
- Overview and Demo of new proposed Python docs theme with dark theme, better navigation features and responsiveness, and cohesive with rest of ecosystem (2 min)
- Continuing Diataxis transformation incrementally (1 min)
- New tooling to extract, check, analyze, visualize and leverage structured data in code & docs, that can be used to improve both Python's and your own (2 min)
- Looking to help: How can you get involved? (1 min)
- Discourse, Discord, attend meetings, help with ongoing projects, share user feedback, contribute!
- Questions (5 min)
- +5 min to the Looking back:
- +2 min to CPython Docs to discuss Diataxis in more detail and include more changes
- +1 min to Devguide to discuss new release human & machine readable info in more detail
- +1 min to PEPs to describe more new author-facing features & peps.json applications
- +1 min to cross-cutting/others to discuss the SEO improvements in more detail and how other projects can use them
- +5 min to the Closer Look:
- +2 min to process and background: Compare before and after and show process more visually
- +2 min to Lessons Learned: Go over more key insights in more detail w/examples
- +1 min to discussing other lessons learned throughout the year
- +5 min to Looking to the future:
- +1 min to discussing and demoing new proposed docs theme
- +2 min to discussion/demo of new docs tooling
- +2 min to discuss other upcoming plans people want to share
Presenting on behalf of and with the support of the Python Docs Community, the SC-designated organization responsible for the Python documentation.
- Organizer of the Python Docs Diataxis Workshop series
- Organizer of the PyCon 2022 Packaging Summit
- Mentored at the PyCon and SciPy mentored sprints
- Accepted and presented a 30-minute talk at SciPy 2020
- Invited to and participated in a SciPy 2020 panel on scientific sensor data processing (public link unavailable)
- Helped develop and edit many proposed talks, workshops, tutorials for SciPys and PyCons in various regions, as well as independently as part of a PSF-funded project, for Spyder project members from 2017-onward
- Given Python-related workshops and short talks locally at my institution (UAH)
- Tutored and mentored numerous students in Python and data analysis
- Core Python: PEP Editor, Core Triager, Docs Team member, regular contributor to workflow, devguide and others
- Spyder: Core developer, docs/website/theme/infra lead maintainer, grant writer/editor, UI/UX
- PyPA: Packaging PEP author, spec/tech writer/editor and community member
- Mjolnir: Author/maintainer of an open source scientific sensor platform
- Conda: Maintainer of a number of Conda-Forge packages
- Maintainer of Pyroma, QtPy, Docrepr, Sub Manager, Serviceinstaller, and other FOSS packages
- Contributor to many other FOSS projects
- NASA-funded satellite, ML/AI and data science researcher
- Lead the transformation of the sqlite3 docs profiled here
- Maintainer of the sqlite3 standard library module
- Python Core Developer
- Docs Team member
- Contributor to CMake, GNU LilyPond and other FOSS projects
- Experiance in Linux, Git, SQLite and others
- Software developer at Inventas AS
Erlend E. Aasland intends to co-present this presentation, specifically being the primary presenter of the section covering the insights from the sqlite3 docs Diataxis revamp, as he was the lead driver for most of the changes.
However, Erlend will need to fly out in the afternoon of April 21 (specific time TBD, as he is still securing a flight). Therefore, a talk the morning of April 21 or earlier is preferred, but if necessary CAM will be equally prepared to present that section of the talk as well if the talk is scheduled at a time when Erlend is not available.
C.A.M. Gerlach is a NASA-funded researcher at UAH specializing in atmospheric science, satellite meteorology and machine learning using open data. However, he has found his his true passion in contributing to the global Python community. Having been introduced to both Python and open source through his work with the Spyder scientific IDE starting in late 2017, CAM continues to be a Spyder core developer with a focus on the UI/UX, docs, website, infrastructure, grants and strategic direction.
In 2021-2022, CAM has become involved in core Python, seeking to bridge the gap between programmers, scientists, documentarians and packagers through his roles as a PEP Editor, Core Triager and Docs Team member, as well as his work on PyPA packaging standards. CAM also develops the Project Mjolnir suite of free and open source extensible scientific sensor software, and is a maintainer of QtPy, Pyroma, Docrepr, FSF-API, Serviceinstaller, Sub Manager and several other FOSS projects, along with a number of Conda-Forge packages.