Documentation triagers

Documentation
1

Hello,
Docs WG has voted to create the Docs Triagers team on GitHub, and add @pauleveritt to it.
I created a team, and I’ll ask an admin to add Paul (and more people, see below).

The Docs triagers will be given GitHub triage rights on the docs-community repo. Soon, as docs-community is cleaned up and the docs WG is up and running, I want to open discussions give them triager rights in places like devguide, peps and python-docs-theme. Repos like typing might want to invite them as well.

For me, this was an experiment in how to run a Docs WG vote, and I learned a few things. One is that it would be good to post here – on the official docs WG communication channel – about any future votes.

Another thing I realized is that I might be taking formal voting processes too seriously :‍)
Also, it turns out that it would be good to fill up the Docs Triagers role with more people, ideally with less overhead than a formal vote.

With that in mind, I’ll add several more people to the Docs Triager role. I’ll take responsibility for their actions until onboarding is ironed out:

To iron out the onboarding, I propose these rules, based the ones for CPython triagers:

  • Any member of the following groups can invite a new Docs Triager:

    Any existing CPython triager can also self-nominate to be a Docs triager. They can request this to a Docs WG member or any core developer, and that person can pass the request to the Python organization admin on GitHub. The request can be made confidentially via a DM in Discourse, or publicly by opening an issue in the core-workflow repository [a template will be provided].

    Every new triager should be announced in the Documentation category in Discourse.

Some details on the vote, for the sake of transparency:

According to the Docs WG charter:

A vote for any proposal will last for 5 days, or when all voting members have voted, whichever comes first. For a proposal to be successful it must have at least two +1’s, more +1’s than -0’s, and no -1. Voting may be done in any venue given agreement of all voting members.

Voting was done on a private Discord channel, with e-mail pings to go there. We don’t all agree with Discord as the venue, but since everyone voted, I count the result as valid.
Since we don’t have a agreed-upon alternative, I currently plan to run the next vote in private Discord channel again, and this time send e-mail pings immediately. (Voting by e-mail should also work, but it’s somewhat inconvenient to count.)

  1. There’s some confusion over whether the SC as a whole is a member of the Docs WG, or each SC member is also a member of the Docs WG. So this is explicit. ↩︎

  2. this is in preparation for having a role for that in the future ↩︎

5 Likes
2

What would the responsibilities of docs triagers be? I recognize most of the names in your list and I’d be glad to see them more involved in Python docs development, but it’s not clear from your message what docs triagers would actually be expected to do.

3

For their pernissions, see GitHub docs. Compared to the Read role, Triagers can:

They also will be members of the @python organization. I think that’s what allows them to be assigned to issues.
Ideally they should be able to fix issue titles, but it seems that’s part of the next level of permissions.

As to what exactly they’d be expected to do – that’s a good question for them, actually. Let’s get back to it after we get some experience on docs-community.
I expect the role would be very similar to CPython triagers, just for docs rather than code.

1 Like
4

Thanks Petr! Lovely to join the new team.

A