Review documentation labels in other Jupyter repos

[ivanov]

There are still some open gems, for example:
https://github.com/jupyter/jupyter/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation

[ericsnekbytes]

@ivanov Thanks for submitting an issue! There are two ideas here that are interesting:

• Have the Docs Working Group regularly check documentation issues in other subprojects
• Take a look at labelling (docs-related labeling and others) in other subprojects and bring those conventions here

Can you clarify which one you mean, or if I missed something? Thanks :)

[ivanov]

I mean more the first - there are already "docs" or "documentation" labeled issues in subprojects, so it seems like a direct way for those interested in documentation work to plug in to understand what those needs are, as well as what previous ideas and efforts there were.

[willingc]

Probably would make good sense to have an aggregated docs issue page that can be viewed from one place instead of each individual repo. Open docs PRs, open docs issues. Also an aggregate of the build status of all repos docs. I used to have a web page that had all of these though it could simply be a markdown file here with badges from all repos/RTD builds.

[ericsnekbytes]

@willingc We can probably work up a quick hub page with links to the subproject's issues on the Jupyter.org docs site (as that would be a natural place for this kind of cross-cutting work for contributors) 🤔

[ericsnekbytes]

PR for that (hub page) is here:

• Added docs-issues-hub page for coordinating docs work. jupyter#716

[krassowski]

Thank you for working on it! I am not convinced that this belongs in jupyter/jupyter docs though. What about using a GitHub project board in this repository instead? I will create one to demonstrate it.

[krassowski]

Ah, the built-in workflows are limited in auto-adding issues limited to a single GitHub organization. Probably can be worked around by using actions (https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions) but this is many-evenings endevour.

[ericsnekbytes]

Thank you for working on it! I am not convinced that this belongs in jupyter/jupyter docs though. What about using a GitHub project board in this repository instead? I will create one to demonstrate it.

Here's my thinking: There has been some discussion in the weekly meetings about using and expanding the Jupyter.org docs site to host materials for maintainers and contributors to Project Jupyter as a whole, which is a natural fit because:

• The site (Jupyter.org docs) already has some of this type of content (contributor guide [with a section for docs], community info, and developer info, on top of some end-user material). This organizational scheme for docs is already widely adopted by other subproject sites: End-user info, developer info, community info, etc).
• All subprojects have a stake in Project-Jupyter as a whole (and in the meta docs), so it makes sense to hold those type of cross-cutting materials and conversations in a shared/central location, rather than trying to coordinate Jupyter-wide work that's relevant to multiple subprojects on a subproject site or repo
• Some resources are shared by all subprojects like the Jupyter blog account, twitter, zoom host account, etcetera. Some efforts also span multiple subprojects. The Jupyter.org docs site is a natural home/nexus for shared resources, materials for administering them, and for coordinated efforts that are not owned by a single subproject. Much of this material (and the knowledge needed to use it) is scattered around inside different subprojects/people's heads presently.
• As Jupyter grows, the need for coordinated project-wide thinking and efforts will likely grow. Since the docs working group spans all of Jupyter, we should lead the way in coordinated cross-project work patterns. Toward that goal (this hub being one small step), we should use jupyter/jupyter to host materials relevant to multiple subprojects, for increased visibility and access to other Jupyter stakeholders, and to encourage the kind of Jupyter-wide cooperation and coordination we seek. The jupyter/jupyter docs site should be a shared watering hole for all the different subprojects, contributors and users in the Jupyter ecosystem to come together, for the shared benefit of our work.

That's a lot! I hope it explains why the jupyter/jupyter docs site is a good place for this hub: It increases visibility and access for other Jupyter stakeholders to a common work stream spanning multiple subprojects (rather than siloing it off here), and it's a (small) step toward building good coordinated, cross-project work patterns around a common, shared space.

[krassowski]

Yeah, but can you embed

an aggregated docs issue page that can be viewed from one place instead of each individual repo. Open docs PRs, open docs issues.

there?

Maybe codetree can do this. Maybe there is no way to do this. https://softwareengineering.stackexchange.com/questions/378094/effective-project-management-spanning-multiple-repos-in-github

[krassowski]

We discussed this today, with Carlos and Nick, including ideas like:

• having a custom repo to mirror documentation issues from sub-projects (using a github actions automation) allowing to use Project Boards and similar (for example copy-pasting the the tile only setting the body as a link to the original issue)
• exploring what https://goodfirstissues.com/ or https://goodfirstissues.dev/ does
• exploring an approach using graphql for querying issues like https://github.com/regro/cf-graph-countyfair
• using https://octobox.io/
• starting with https://github.com/search?q=label%3Adocumentation+owner%3Ajupyterlab+owner%3Ajupyter-server++owner%3Ajupyterhub+owner%3Ajupyter-widgets&type=issues&state=open&s=created&o=desc