# Documentation Community's Team Meeting (April 4, 2022) ## Roll call (Name / `@GitHubUsername`) - Petr / `@encukou` - Mariatta / `@mariatta` - Ned / `@nedbat` - Fred Drake / `@freddrake` - CAM Gerlach / `@CAM-Gerlach` ## Quick updates - Introductions > 60 second updates on things you have been up to, questions you have, or developments you think people should know about. Please add yourself, and if you do not have an update to share, you can pass. Office hours @BostonPython - [choose your own adventure](https://github.com/nedbat/cyoa) as a way to branch during installation instructions. ## Reports and celebrations > This is a place to make announcements (without a need for discussion). This is also a great place to give shout-outs to contributors! We'll read through these at the beginning of the meeting. ## Agenda items > Let's collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together. ### PEP 588 -- GitHub Issues Migration Plan GitHub Issues migration plan [python/peps#2497](https://github.com/python/peps/issues/2497) We will update PEP 588 with current plan of migration. Don't create yet another PEP. Devguide PR: [python/devguide#814](https://github.com/python/devguide/pull/814) - [x] **Mariatta**: reply ### Clean up, fix and improve grammar, phrasing, syntax/links and overall prose quality in charter - Who should review [PR29](https://github.com/python/docs-community/pull/29)? What's the official status of the charter? - [ ] **Ned**: Review the PR - [ ] **Mariatta**: Review the PR ### Python Language Summit @ PyCon US - If there's any updates/issues that would be relevant to the Python core developers, this would be a good place for presenting that for discussion! - Still in planning stage, but worth it to start thinking about it now, if you want to bring up something for discussion. - Signup: [us.pycon.org/2022/events/language-summit/](https://us.pycon.org/2022/events/language-summit/) - We talked about the docs group at the last 2 lang summits. This time the group has started! - Desires for revamping the main CPython documentation theme might be a topic for discussion? - Lightning talk sounds good ### Structuring Docs, Devguide, and PEPs * Some PEPs are turning into long-lived documentations. * Packaging PEPs used to be, moving to packaging.python.org * typing is moving into a similar situation. * `__future__` page in Python docs is also a list of PEP references. * Helping the typing community move their PEPs into a separate spot. * In the Python documentation? Outside of Python documentation? * There's an ongoing effort? * [typing.readthedocs.io](https://typing.readthedocs.io/en/latest/) * Should the typing specifications live in Python docs or externally? * The fact that core developers don't care strongly about typing documentation isn't a good reason to keep them external to it. * PEPs are not documentation. * Getting the typing folks to agree that their work needs to be in the Python documentation. * [discussion of what goes in Python docs vs externally] * If a user is reading only the Python docs, is that sufficient information to understand? - PyPA has standards, and uses PEPs as proposals to change the standards - Should we expand the scope of the Python docs? - What's the scope of this group? Are we advisors, or do we do the work? * Potentially WSGI spec and similar * Release PEPs? ## Issue triage > I'm not sure this is the _best_ use of everyone's time on this call but, if we have time: sure, why not! [name=Pradyun] > I agree, this seems like in-the-trenches work we can get to after establishing the shape of the effort and group [name=Ned] For [each issue](https://github.com/python/docs-community/issues) we should decide: - What's blocking the issue? (Is it a decision the WG should make?) - How can we help move it forward? Discussion outside the meeting should be on the issues :) - [ ] **CAM**: Open Sphinx issue to improve indexing ordering and list builtins ### Bringing in new people - When “herding cats”, play into people's existing strengths/interests - Give people smaller, manageable tasks. - [ ] **Petr**: think about how to generate manageable tasks ### New WG member? - CAM would be a good new voting member of the formal WG - OTOH, the formal WG isn't that important, so figuring out how to get new people into it might not be a good priority ### Docs WG Docs The group's docs are incomplete. Should we fill in the blanks? Scrap some pages and focus on docs? - Adding and onboarding new workgroup members [docs-community.readthedocs.io/en/latest/workgroup/adding-members.html](https://docs-community.readthedocs.io/en/latest/workgroup/adding-members.html) - Milestones and roadmaps [docs-community.readthedocs.io/en/latest/workgroup/milestones.html](https://docs-community.readthedocs.io/en/latest/workgroup/milestones.html) - Discussion platform [docs-community.readthedocs.io/en/latest/community/contributing.html](https://docs-community.readthedocs.io/en/latest/community/contributing.html) Discourse, Discord, GH issues, any more? - Documentation Team [docs-community.readthedocs.io/en/latest/community/team.html](https://docs-community.readthedocs.io/en/latest/community/team.html) Who should be in the Community team? ### Documentation guidance > Having a clear and opinionated style guide can enable more contributions. It will clarify expectations, making it easier to create pull requests that will get accepted. It will remove individual ownership of pages, which creates roadblocks to merging. [name=Ned] The style guide could cover questions like: - How to best use code examples - When to use "roughly equivalent" implementations - How to divide different kinds of documentation - [documentation.divio.com](https://documentation.divio.com/) - [diataxis.fr](https://diataxis.fr/) - First step could be understanding how the current docs align with the diataxis framework Book suggestion: [Docs for Developers](https://docsfordevelopers.com/) - [ ] **Petr**: Gain consensus on Diataxis framework