Planning Meeting: Community & Documentation

Date: Thursday 11:30 - 12:30 AM
Topics: Documentation, Community Building, Tutorial Infrastructure (SciPy notes)
Issues: #7, #9, #13, #21, #19

Attendees

  • Juanita Gomez
  • Dan McCloy
  • Paul Ivanov
  • Sanket Verma
  • Matt Haberland
  • Stéfan van der Walt
  • Inessa Pawson
  • Dan Allan
  • Isaac Virshup
  • Henry Schreiner
  • Greg Lee
  • Jarrod Millman
  • Brigitta Sipőcz
  • Mridul Seth

Ideas from issues

Community Building

Sanket: Building an onboarding guide for newcomers and creating a guide/manual for scientific community managers

  • lots of documentation on how to begin contributing, but not how to do other things, that does not involve writing code

  • SPEC for community building and outreach

    • not a lot of formal guidelines for how people can do
    • [leah] check out CSCCE - they have a lot of resources on community management and also courses you can take. i took one of them and plan to have my full time community manager go through their training. These also have a big grant with rOpenSci called POSE that will focus on training and contributors.

  • Sanket has good recommendations on

    • community meetings
    • note taking
    • office hours
    • list "good first issue" / "low-hanging fruit" on a separate page

  • Juanita has similar document about role of community managers

    • composed while working at QuanSight
    • "why is it important to have a community manager"
    • start a "community managers' community meetings"
      • some community managers don't have formal training in managing communities

  • Sanket

  • Dan McCloy

  • Dan Allan

  • Juanita

    • Let's compile a list of questions that we want to answer during the summit

  • Jarrod and Isaac

    • Overwhelmed by newcomers
      • Having a resource to handle the newcomers would be good

Community manager docs questions

  • How does a project community's needs evolve as it reaches different scales? E.g. single lab group, multi-group collaboration where everyone knows each other, larger collaboration where not everyone knows each other…
  • How to hire a good community manager?
  • Why is it important to have a community manager?
  • What is the role of a community manager?
  • What are the challenges community-builders have faced?
  • Tools for community outreach and building
    • Templates for community meetings
    • Tools to manage social media accounts
    • Tools for video/image editing, compressing, etc..
  • What are some SEO tricks to deprecate older docs, and surface current docs?
    • canonical URL
  • Strategies for reducing and triaging the support load
    • FAQs
      • Nita: have a good FAQ. Draw real world problems from StackOverflow or GitHub issues, so that there's an official right answer in the docs
    • GitHub Issue Templates?

Resources for newcomers

Tutorial Infrastructure

  • Based on work done for, e.g., NumPy & NetworkX; lots of projects have similar needs
  • Also related to CI infrastructure topic
  • Moving from MyBinder -> JupyterLite
  • Testing tutorials using a version matrix similar to how the library is tested
  • One idea: all projects should communicate / implement any improvements into NumPy so that it gets broad visibility as a best practice
  • Would be great if projects could built joint resources, instead of re-inventing the wheel
    • Related: bot for checking labeling & milestones
    • Related: release notes script, copied between several projects such as scikit-image, …; newest version in Napari
    • "If I could have installed it I wouldn't have forked it"

Ross: One thing I'd personally be interested in is seeing whether/how various tools can be used in conjunction with one another. For example, there are several tutorials sites (numpy-tutorials, nx-guides) built on top of the executable books stack that would also benefit from e.g. the thumbnail feature from sphinx-gallery. It's not immediately obvious how the executablebook sphinx extensions & sphinx-gallery can be used together.

In a similar but broader vein - I'd like to investigate the browser-native tooling and see how well/easily existing tutorial content (based on static site generation) is supported.

Ecosystem-level tutorial / documentation content

Daniel McCloy: There are lots of things that don't need separate documentation for each package; things like

  • standard GitHub setup for contributors (fork, clone, add upstream, don't open PRs from main, etc)
  • explanation of CIs and how to view their logs
  • project management / workflows. This one is more aimed at maintainers, and has the goal of making it easier for contributors from other parts of the ecosystem to jump in and contribute to other packages without too much friction. Here I'm thinking of things like pre-commit setup, PR merge criteria, etc: probably there won't be general agreement on something like PR merge criteria across the ecosystem, but we could at least agree upon a standard place to write down what the PR merge policy is, so that a new contrib could easily find that information (CONTRIBUTING.md?) regardless of what package they happen to be contributing to.

obviously there will be some degree of variability across packages in how each of these things are done, but that's an opportunity for figuring out which ones have a clear best-practice (that could be codified in a SPEC?) and which are cases of "reasonable packages will disagree". For the latter cases, the ecosystem-level tutorial would be either more conceptual (individual package docs fill in the details) or simply not exist.

  • Isaac
    • is this documentation for ecosystem developers or ecosystem users?
  • Dan M
    • example: have one page to point everyone to about how git works.
    • new version of https://github.com/matthew-brett/gitwash
    • {Leah} - i am working on moving all of this content to a new website that i can maintain. will be creating some pilot videos. its part of work from our grant and also an experiment with video / website content combo. I also have some contributor to oss lessons that i used to teach that dealt with interacting with people on github.

SciPy Lecture Notes

Meeting notes

Select a repo