EC Approval for a new "Docs Working Group"
ericsnekbytes opened this issue · comments
We are proposing a new Documentation Working Group for the improvement of docs across the entire Jupyter ecosystem. Though we are awaiting official approval, our work is already underway: Docs improvements for subprojects have been delivered, and we meet weekly to discuss and organize our efforts.
In short, here are the pillars of our mission (a full proposal, charter and more details are available below):
- Improve all aspects of documentation across the Jupyter ecosystem
- Make high quality documentation that is clear, comprehensive, inclusive, and serves the varying needs of Jupyter's diverse community
- Engage with the community to help users with Jupyter products, discover their needs, and connect them with relevant information, expertise and resources
For lengthy discussion around the idea and motivations for the Docs Working Group, please see the initial proposal and discussion issue. Documents further detailing the group's governance and operating procedures are available here (not all are listed below, check the team compass for a complete listing):
Please let us know if any changes need to be made, we can work with the EC to incorporate those :) Thank you!
Hi Eric - many thanks for sharing this here. I want to be sure we're not crossing wires here with the Docs group waiting for the EC while the EC is waiting for the Docs group. Please confirm you're still in the feedback stage from the community and that when this is complete you will reach out to the EC for approval of the charter.
We're ready for the EC to review the charter, as we reached consensus in our weekly meeting today to move ahead. Thanks!
That's great news, I have created a checklist and there is a voting template to get the charter approved. Can you please review: https://github.com/jupyter/governance/pull/187/files#diff-c41509ee050ce3fe43e575d83921013af2aeeb8c31347550bc49be5c2808e52c and let me know if you have any questions? The only thing I will add is that since this is a Working Group (vs a Standing Committee) only the EC needs to vote.
I'll be working through these today, thank you!
Here's current status, many of these items should be completed already through Docs Working Group member collaboration:
Checklist / Overview of Process
- Start a discussion with the EC: Post an issue on Team Compass for Governance or attend EC office hours. Find join details on the community calendar. Here are some topics to consider during that conversation [pending link-content not available yet].
- Request a folder in the Jupyter shared drive for all official files (documents, spreadsheets, etc).
- Find two or more founding members to create a charter draft and agree to process for writing a charter
- Create charter (pending link - see template)
- Submit charter for review in the governance repo under the charter directory.
- Open the pull request as a draft and let the EC and SSC know that you’re ready for review
- Once the review is addressed and the final draft is ready, take the pull request out of draft and update the description to include a deadline
- See voting template to simplify logistics of calling for a vote.
- Recruit additional members for committee (ideally between 4 - 8 total)
- (Optional) Once your charter is approved, publicly share the news with the community on the Jupyter blog. Include a way for the community to get in contact with you (Category on Discourse, Team Compass, or Email).
Questions:
- Do you have a suggestion for who to contact for requesting access to the google drive folder? Otherwise I would probably ask the security group for access
- I could use some clarity on the charter review PR. Is the idea to edit this with feedback from the EC, and if there's feedback, to rewrite? The instructions say to call for a vote, does this mean to ask Docs Working Group members to vote on the changes if there are any? If we have changes there, I will have to backmerge those into the Docs Working Group repo where the current charter is 🤔
- Is this where the PR will go?
Thanks Eric. We're open to feedback on the documentation since you're the first group who is attempting to use what we wrote. There are definitely things we may have missed since I have been involved with so many sides of this process.
Here are the answers to your current questions, feel free to ask more.
- Shared drive folder: I've given you access. This folder lives in a shared NumFOCUS drive and it looks like they have updated their default settings. I can't make you manager so that you can add others. The highest permission I could give you was "content manager". I'm happy to add the rest of the people in the Working Group if you can send me names and emails or have those folks email me directly to request. I'll check in with NF about this but in the meantime we can use this workaround. I do think it would be ideal if your group could manage those permissions directly.
- The idea for the charter review is a feedback stage for both the EC and the wider community. By the time it reaches this phase, It is assumed that the council of your working group has reached consensus and have approved what is shared. Note that founding members would be anyone who helped you start the working group which may or may not be the same as the decision making body needed to fulfill the requirement of having a council for your group. Therefore, the vote that needs to happen to approve your charter is among the Executive Council.
- @marthacryan is the one who helped me with the submission of charters on GH and with creating the voting template. Mentioning her here to request that she answer your questions for logistics for those PR's in bullets 2 and 3.
Hi @Ruv7, @RRosio has created the charter PR in the governance repo, we're ready for a vote!
Some feedback for improving this process:
- More explanation, context, and guidance would make this process easier to understand and complete
- When someone opens an issue here, it would be nice for the responder to have a templated message that:
- Says "Hi" or "Welcome"
- Uses friendly language that makes contributors feel welcome and acknowledges their efforts to improve the Jupyter ecosystem (@isabela-pf has template documents [here, for instance] that excel at providing a positive, welcoming voice)
- Gives a friendly explanation (the why?) and narrative for the process at a high level, then briefly explains each phase (or checklist step) along with instructions for carrying them out
- From the checklist: "Open the pull request as a draft and let the EC and SSC know that you’re ready for review".
- Does "review" mean that the EC intends to do a typical PR review on your charter, then have the requestor make changes and resubmit? Or does "review" mean the actual vote?
- My understanding, from the checklist, is that there will be a feedback period where the EC will suggest changes to the charter, and I will address them with my group, then request a re-review, and at some point a vote for approval will happen.
- If the vote is happening in a different place, what is this issue for? It seems to make more sense to do the vote on this issue, or to have the EC responder do this or shepherd the requestor through it (the steps for the charter PR seem overly complex and the rationale behind them is unclear). Just some narrative and explanation about how this process will unfold would be very helpful, at a minimum.
- The checklist says "Once the review is addressed and the final draft is ready, take the pull request out of draft and update the description to include a deadline"...
- What do you mean by deadline? What is it for? Is the "review" the EC's combined feedback on your charter PR? How do I know when the PR is in a "final" state? Many of these things are ambiguous/unclear, and/or I don't know exactly why I'm doing them.
- From the checklist: "Open the pull request as a draft and let the EC and SSC know that you’re ready for review".
- Perhaps some of this stuff could be streamlined via github actions/workflows to hide the complexities away from the requestor
- A "Guide/Walkthrough" document could be helpful
Maybe some of this is already in the works, as you've mentioned that these processes are still in development. I hope this helps! :D
The changes have been added, and we're ready for review over on the charter PR!
Thanks for this feedback and for taking the time to write this up. I'll work with Martha Cryan who helped me create this checklist to continue making improvements.
We've now merged the PR creating the docs working group. Thanks everyone for working through this. I'm excited for great things to come!