Consider using a GitHub issue for community meeting notes

[choldgraf]

Context

Right now we post all of our community meeting notes to the Sphinx documentation that is defined by this repository (and at docs.jupyter.org). However, making commits to Sphinx docs often requires several steps and actions by people, involving a decent amount of "toil".

I've noticed several parts of the Jupyterverse using a slightly different pattern that goes something like:

• Every 6 months, open an issue for meeting notes for that time period
• Use a HackMD to organize the meeting and take all notes
• At the end of the meeting, post a comment in the issue with meeting notes
• Add a link to that comment in a markdown table at the top of the issue

Examples of this:

• Meeting Notes 2022 jupyter-server/team-compass#15
• Weekly Team Meetings: Jan-Jun 2022 jupyterlab/frontends-team-compass#135

I'm curious if others think adopting this approach, rather than using Sphinx, would be a net-improvement in quality of live for maintainers of this repository. @isabela-pf I'd be curious to hear what you think since you have put in a lot of work here lately! maybe also @Zsailer would be willing to comment on whether this seems reasonable for this repo given his experience in lab/server

[isabela-pf]

Hey there, thanks for the idea and the tag! I do think this is a possible change, and one I am familiar with the process of. Before I get too far into it, I want to note that I am open to changing to storing things in issues if it's preferred .

Some pros I can imagine:

• I 100% agree that this would lower the number of steps and people needed. It would take less immediate maintenance.
• It might be a friendlier way for people to contribute without having to open a PR.

Some cons I can imagine:

• I'm not sure notes are discoverable on GitHub issues unless someone is already here or is directly linked to them.
• Even though I've seen critiques of it, I think the community and wider open source communities still value commits above all else. Community work is already sidelined and difficult to quantify, and I think this could further separate the work from the ways we tend to measure value.
• Unless we are running some kind of intentional backup, I don't think issues are preserved if anything happens to the repo or we need to move where the code is hosted. Notes would be lost if issues were the only place they existed (though it's fixable).

[choldgraf]

Hey @isabela-pf - thanks for these ideas! A few quick thoughts from me:

I'm not sure notes are discoverable on GitHub issues unless someone is already here or is directly linked to them.

I'd imagine defining an issue label for team notes, and then having a link in our documentation that takes you to a list of all issues with that label. Or perhaps a link that takes you to a search page in GitHub that lets people search all issues with that label.

I think one benefit of this is that github search is more powerful than Sphinx search.

If we wanna get wild, we could even write a little script that scrapes all of the issues in GitHub with a particular label, and generates notes in our Sphinx documentation from their comments :-)

Even though I've seen critiques of it, I think the community and wider open source communities still value commits above all else. Community work is already sidelined and difficult to quantify, and I think this could further separate the work from the ways we tend to measure value.

I agree with this concern. Are you suggesting that because taking and updating these notes would not involve a commit in a git repository, it would be more invisible? Are there other ways we could boost the visibility of this work?

Unless we are running some kind of intentional backup, I don't think issues are preserved if anything happens to the repo or we need to move where the code is hosted. Notes would be lost if issues were the only place they existed (though it's fixable).

My hope is that it'd be relatively easy to scrap all of the content of these issues and place them somewhere else if need be, assuming that the GitHub API was still available for us to use. But I agree with the concern that using a proprietary service for archival purposes has downsides like this.

[Zsailer]

Seems like it would be worth creating some sort of GA workflow to fetch meeting notes from the issue and create a PR to the readthedocs repo. This could run nightly or weekly. A few teams (Notebook, Server, and JLab) are using issues to track the notes over time. Adding something like this would be of great value.

We could add it to the team-compass-template repo that @afshin created: https://github.com/jupyter/team-compass-template

[isabela-pf]

Okay! Reply time.

In response to @choldgraf

If we wanna get wild, we could even write a little script that scrapes all of the issues in GitHub with a particular label, and generates notes in our Sphinx documentation from their comments :-)

I think this would be the best of both worlds, though I understand if this can't be done right away since it seems like it might be custom work. You still have the good GitHub search, but also provide a non-GitHub option for the community. I think I'm on board.

I agree with this concern. Are you suggesting that because taking and updating these notes would not involve a commit in a git repository, it would be more invisible? Are there other ways we could boost the visibility of this work?

Yup, that's exactly it. It's (fortunately) not a problem I often have to deal with in my current situation, but commits are a pleasantly quantifiable and easily accepted argument I've needed to back up community work Ive done in the past. Sure I wish that wasn't the case, but it has been and could be again. I'm also noting this because I think it can discourage people who may want to do community work because they know it doesn't have the same hierarchy and/or "I can prove this to my boss" power as some other tasks.

As for what other ways we could boost the work, I'm not sure at the moment. I know some projects have been adopting the All Contributors system, but I'm personally not all sold on it (especially since I think it relies on some degree of manual maintenance). I can put this on my list to ask around.

---

In response to @Zsailer

A few teams (Notebook, Server, and JLab) are using issues to track the notes over time. Adding something like this would be of great value.

Yes, I'm all for solutions we could use across projects as well! Good point!

---

Just to be clear, I'm open to moving forward with this if y'all want. Is there a next step you'd want me to do, or just post the May community call notes as an issue and go from there?

[isabela-pf]

Okay! Reply time.

In response to @choldgraf

If we wanna get wild, we could even write a little script that scrapes all of the issues in GitHub with a particular label, and generates notes in our Sphinx documentation from their comments :-)

I think this would be the best of both worlds, though I understand if this can't be done right away since it seems like it might be custom work. You still have the good GitHub search, but also provide a non-GitHub option for the community. I think I'm on board.

I agree with this concern. Are you suggesting that because taking and updating these notes would not involve a commit in a git repository, it would be more invisible? Are there other ways we could boost the visibility of this work?

Yup, that's exactly it. It's (fortunately) not a problem I often have to deal with in my current situation, but commits are a pleasantly quantifiable and easily accepted argument I've needed to back up community work Ive done in the past. Sure I wish that wasn't the case, but it has been and could be again. I'm also noting this because I think it can discourage people who may want to do community work because they know it doesn't have the same hierarchy and/or "I can prove this to my boss" power as some other tasks.

As for what other ways we could boost the work, I'm not sure at the moment. I know some projects have been adopting the All Contributors system, but I'm personally not all sold on it (especially since I think it relies on some degree of manual maintenance). I can put this on my list to ask around.

---

In response to @Zsailer

A few teams (Notebook, Server, and JLab) are using issues to track the notes over time. Adding something like this would be of great value.

Yes, I'm all for solutions we could use across projects as well! Good point!

---

Just to be clear, I'm open to moving forward with this if y'all want. Is there a next step you'd want me to do, or just post the May community call notes as an issue and go from there?

[isabela-pf]

I'm following up on this issue because I'd like to post the May meeting notes!

I can put them in an issue (edit: done at #614), but I'd like to know the long term solution so anyone looking for the notes doesn't get confused navigating between two storage places. If I don't hear in a week, I'll post the May notes as a PR too so they can live with the other notes as is.

[choldgraf]

@isabela-pf what would be your preferred path forward? You are the person putting time into doing this work so in my opinion, we should optimize around a person in your position!