Docs WG Agenda/Minutes – February 2022#
Time: 22:00 UTC
This HackMD: https://hackmd.io/@encukou/pydocswg1
GitHub issue: Agenda Planning Issue
Calendar for future meetings: XXX
By participating in this meeting, you are agreeing to abide by and uphold the PSF Code of Conduct. Please take a second to read through it!
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.
On the first meeting, let’s use this slot for an introduction!
Why are you interested in docs?
How do you want to help?
What’s blocking you?
[name] / affiliation / github username
[Pradyun] / :shrug: / @pradyunsg
[willingc] / Core Dev / willingc
[Ned] / edX, Open edX, Boston Python, Coverage.py / @nedbat
[Petr] / Core Dev & SC / @encukou
Mariatta / Core Dev / @mariatta
[CAM] @CAM-Gerlach PEP Editor / NASA Scientist
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.
Welcome Documentarians :smile:
TIL about HackMD’s
[name=Pradyun]syntax, and it’s great! [Pradyun]
editor’s note: it doesn’t work outside HackMD, and has been replaced by [name] in this document
I’ve been making a decent amount of progress on the Sphinx theme, and spent some time reading the implementation of https://github.com/python/docsbuild-scripts [Pradyun]
Thanks @encukou for kicking this off. :tada: [willingc]
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.
What we do and how we work#
I think the most important thing to work out is the overall shape of the group. What kinds of work will we do? How will we get it done? [Ned]
[Ned] would be happy to do edits, but not before there’s agreement in a wider group. A “guidance document is at the end of the document”
[Carol] We started the group to provide editorial guidance that included non-core devs as well as core devs that lets people contribute.
[Petr] If we come up with guidance, the Docs-WG should probably ratify it. The PSF / SC might need to ratify this. Will have community input, but Docs-WG is the final arbiter.
[Julien] Every one of us can review PRs; if 6 of us say this is good, it’ll be very hard for people to say “this is my kingdom, don’t touch it”.
[Carol] Should there be someone who causes friction, goes to CoC or SC.
[Ned] Does “6 of us review” mean that we don’t need guidance written down prior to it?
[Julien] Maybe we need guidelines, maybe not. We can definitely review PRs.
[Petr] We don’t need to write the rules before hand, to block our work. We can start by just reviewing stuff.
[Carol] I think that’s a good way to start. Because this is both core devs& non-core devs, if there’s an issue it should come back to this agenda, instead of a mailing list.
[Ned] Right, writing rules shouldn’t block our work. But how do we determine a PR is good? Having guidance up front is a good way not only to avoid conflict, but also guide people doing the work.
[James] Example: someone was confused print returns None (ref: https://bugs.python.org/issue46282). Let’s add it to the builtins page! But someone said it wouldn’t be appropriate to add return value to all the builtins. Guidance, like dividing docs into 4 quadrants, would help.
[CAM] From experience maintaining the Spyder docs, it’s finding the right balance between guidelines for consistency + better onboarding, and the pragmatic aspects of avoiding nit-picking – focusing on the more important aspects like clarity.
[Carol] Another thing to keep in mind: we can create new docs. e.g. print returns None might be a completely new set of docs. A user could find it with search, but doesn’t need to edit the reference docs.
[James] Optimising for the audience is indeed relevant. An experienced dev knows print returns None, but a beginner would miss the information buried in the middle of a paragraph. Targeting for different audiences can make it more optimised for it.
Audience is a good point on consumers of documentation.
[James - Ned] [discussion on what belongs in reference documentation, and how guidance could come into play with that]
[Petr] Guidance can contain examples.
[CAM] As a user, separating beginner/intermediate/advanced for reference documentation. Very clearly documenting parameters & return value, as in scientific library docs, is very valuable – you don’t need to skim the prose for these.
Should we have a doc that explains to users how to use Intellisense for PyCharm or VSCode so that people understand docstrings can be pulled up on hover.
[Petr] Good to have folks with different experience here.
[CAM] Indeed! It’s super valuable in working on documentation to have multiple experience levels.
[Petr] Autogeneration is related to the skimming-prose aspects we just discussed – let’s defer that for later.
Review PRs to understand current situation
Craft guidelines as needed for making contribution more effective
[Paul (in Carol’s voice)] Instead of “golden eggs” I care about “golden goose” - the people. We should make it fun to contribute, read and use, can use docs to onboard underrepresented groups.
[James] The thing that resonated with me was the “fast path” issue. I didn’t understand the workflow. Even if Docs WG is the place where people submit ideas and others implement them, that would be a huge value. [Carol] +100
[Julien] How useful is the CLA? Why do we have a CLA? It’s a barrier
[Mariatta] There are plans to improve the workflow for that, since currently it’s manual at the moment – there’s exploration of automating this at the moment (cla-assistant). I would like to improve this personally, there’s an open issue about this.
[Petr] This is being looked into right now, either Ee or Łukaz.
[Mariatta] Do we need CLA for documentation?
[Julien] We don’t have one for the French translation – just have a note that all contributions are CC0.
[Petr] That’s a question for VanL.
[CAM] IANAL, it’s probably not possible to exempt the docs from the CLA?
[Julien] We should document why we have a CLA.
[Ned] Sounds like a good issue to file.
[Petr] Filing an issue. (https://github.com/python/docs-community/issues/17)
[Paul] You can probably blame the CLA process on me.
[CAM] It’s a bit of a gray area, of what is “substantial” work that’d be copyrightable.
[Petr] Let’s talk to a lawyer.
[James] The key question for the WG: How do people interact with the CLA, does it cause headaches etc.
[Ned] We should discuss other stuff, and not dive too deep on the CLA issue.
[discussion on PyCon sprints, potentially running a usability study, how that’s complicated etc]
I’m not sure this is the best use of everyone’s time on this call but, if we have time: sure, why not! [Pradyun] I agree, this seems like in-the-trenches work we can get to after establishing the shape of the effort and group [Ned]
For each issue we should decide:
What’s blocking the issue? (Is it a decision the WG should make?)
How can we help move it forward?
Keep discussions as much on GitHub as possible, using Discord as a mechanism to notify people for second opinions.
Avoid having discussions in closed groups, to the level deemed reasonable.
Pradyun, CAM, Petr are used to it
better moderation tools
Useful for reaching out to the wider python community
Documentation category is a bit hidden – subtag of core development. Move it to a top-level category?
Preferred communication tool. Public, asynchronous.
GitHub team under the
python org? Would have issues with adding people to the
(We didn't actually get to this on the meeting)
From the issue tracker:
Migration of theme to modern responsive theme https://github.com/python/docs-community/issues/1
This is coming along, albeit slower than I’d like. I’m resisting the urge to strive for perfect but, also, I’d like to check all the boxes? [Pradyun]
Post the application process for workgroup members https://github.com/python/docs-community/issues/3
Enhancing the switchers setup https://github.com/python/docs-community/issues/4
This is related to #14. :P [Pradyun]
Suggestions from Python Language Summit https://github.com/python/docs-community/issues/6
Mobile friendly theme for wiki.python.org https://github.com/python/docs-community/issues/7
I think a new theme would be nicest, even if it’s the most “costly” in terms of effort+time? None of the existing themes look particularly great. [Pradyun]
Suggestions and ideas from Typing Summit https://github.com/python/docs-community/issues/8
French translation sprint https://github.com/python/docs-community/issues/9
Use Sphinx for pep builds and better rendering https://github.com/python/docs-community/issues/10
This seems to be progressing well mostly thanks to Adam’s work; we just need to do some tweaks to the styling and appearance; main blocker is just PEP 676’s approval and then getting the infra moved over to whatever we decide on (RTD, GHP, Netlify, etc). A huge improvement and going to unlock a lot of possibilities going forward while being far more maintainable than the hacked-together legacy csystem. I’m a little unsure if this is directly within scope here, though. [CAM-Gerlach]
Is it in scope? :)
Having a “fast path” for documentation contributions https://github.com/python/docs-community/issues/13
Move language selection to a dedicated page? https://github.com/python/docs-community/issues/14
This seems like a good idea. :P [the-guy-who-filed-the-issue AKA Pradyun]
Docs WG monthly meeting #1 https://github.com/python/docs-community/issues/15
This one is a bit self-recursive, eh? :) [CAM-Gerlach]
Docs WG Docs#
(We didn't actually get to this on the meeting)
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 https://docs-community.readthedocs.io/en/latest/workgroup/adding-members.html
Milestones and roadmaps https://docs-community.readthedocs.io/en/latest/workgroup/milestones.html
Discussion platform https://docs-community.readthedocs.io/en/latest/community/contributing.html
Discourse, Discord, GH issues, any more?
Documentation Team https://docs-community.readthedocs.io/en/latest/community/team.html
Who should be in the Community team?
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. [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
Book suggestion: Docs for Developers
Plan is to meet every month.
March 7th, same time as this? 2pm PT; 5 pm ET; 22:00 UTC
No one is opposed.
Meetings over Discord? Yes, good.