Docs WG Agenda/Minutes – February 2022#

  • Date: 2022-01-07

  • 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?

Roll call:#

  • [name] / affiliation / github username

  • [Pradyun] / :shrug: / @pradyunsg

  • [willingc] / Core Dev / willingc

  • [Ned] / edX, Open edX, Boston Python, Coverage.py / @nedbat

  • James

  • [Petr] / Core Dev & SC / @encukou

  • Mariatta / Core Dev / @mariatta

  • [CAM] @CAM-Gerlach PEP Editor / NASA Scientist

  • Paul

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]

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.

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.

Summary

  • Improve documentation

  • 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]

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! [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?

Communication

  • 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.

Discourse?

  • Pradyun, CAM, Petr are used to it

  • Discord:

    • Async chat

    • better moderation tools

  • Discourse:

    • 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?

  • Github:

    • Preferred communication tool. Public, asynchronous.

GitHub team under the python org? Would have issues with adding people to the python org.

(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]

  • ReadTheDocs https://github.com/python/docs-community/issues/5

  • 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?

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. [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

    • https://documentation.divio.com/

    • https://diataxis.fr/

Book suggestion: Docs for Developers

Next meeting#

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.