Create a documentation site for our Outreachy workflows, powered by ReadTheDocs

[sgibson91]

Many communities participating in Outreachy (or GSoC, or similar) have their own set of documentation detailing their own processes for participation in these initiatives, and the expectations for everyone involved. We should build something similar so that it is more repeatable for JupyterHub to participate in the future.

There is already a bunch of great resources like this already so, crucially, we should point to those docs and only write new stuff where it's specific/bespoke to the JupyterHub community. Examples:

• http://intermine.org/internships/
• https://openlifesci.org/
• https://zulip.readthedocs.io/en/latest/outreach/index.html

One reason that I suggested #43 was because I think it would be nice to have a couple of auto-generated pages with tables listing: project proposals and their status; currently active contribution issues.

Suggested structure

We should break the docs down by role: Community Organiser (currently me), Mentors, Interns

• Community Organiser
  • Responsibilities and Expectations: Document the Community Coordinator role and its responsibilities #175
    • Approving projects/mentors
    • Comms
      • Connecting mentors and interns
      • Arranging meetings, i.e., contribution period post-mortems and application review
  • The Outreachy platform
    • Transferring organisers
      • Need to investigate how to reduce this as a bottleneck
  • Funding and Grant Writing/Sustainability
    • Interns
      • Paying them ourselves
      • Using the Outreachy General Fund or sponsored grants
    • Mentors
      • Pay a mentor for their time
    • Discretionary fund
      • Mentor training
      • Mentor honoraria (if not paying them fully)
      • Contracting folk to respond to GitHub/gitter questions specifically during the contribution period
  • Collaborations
    • Organising shared mentor training with OLS
  • Cohorts of interns: Community Coordinator Guide: Cohort Calls #169
    • Motivation for cohort-based learning
    • How to run a cohort call
    • Templates for cohort calls: Add templates for Cohort Calls #170
• Mentors
  • Why should you be a mentor?: Mentor Guide: Add info about becoming a mentor #158
    • Benefits / promo-pack
    • Training
    • Co-mentoring is cool!
    • Expectations of a mentor
      • Time commitment
      • The contribution period
  • Project proposals: Document project proposal process #183
    • How to scope a project proposal in this repo
      • Reference the labelling system and issue template: Create a new labelling system for the repo #43 Create issue templates for the repo #44
    • How to submit a project proposal to the Outreachy platform
    • How to assign a co-mentor to a project proposal
  • Contribution issues: The Contribution Period: A mentor's guide #139
    • How to create contribution issues in this repo
      • Reference the labelling system and issue template: Create a new labelling system for the repo #43 Create issue templates for the repo #44
    • How to write a good contribution issue¹
    • Examples²,³,⁴,⁵
    • "Locking mechanisms" for issues that create PRs to minimise merge conflicts
    • Results of current contribution period retrospective
  • Reviewing project applications
    • Guidelines/criteria for reviewing applications and choosing an intern
    • Add process for reviewing applicants to mentor guide #132
  • During internship: Mentor Guide: Explain what to expect during the internship #165
    • Feedback
• Interns
  • Why you should intern with JupyterHub
    • Intern testimonials: Post internship: Gather testimonials from the interns #166
    • Intern blogs: List Outreachy interns on the website #161
  • How to find contribution issues and what the labels mean: Intern Guide: How to contribute to JupyterHub and the Contribution phase #154
  • How to put together your application⁶: Intern Guide: Preparing the final application #142
  • During the internship: Intern Guide: Explain what to expect during the internship #164
    • Meeting your mentor
    • Cohort calls
    • Feedback
    • Extending the internship
  • ...

Footnotes

1. https://phabricator.wikimedia.org/project/view/169/ ↩

2. https://phabricator.wikimedia.org/T302242 ↩

3. https://phabricator.wikimedia.org/T276274 ↩

4. https://phabricator.wikimedia.org/T205199 ↩

5. https://github.com/zulip/zulip/issues/23101 ↩

6. https://zulip.readthedocs.io/en/latest/outreach/apply.html#putting-together-your-application ↩

[sgibson91]

Capturing ideas from Slack with @GeorgianaElena:

• intern testimonials: motivation to do Outreachy with us!
• intern blogs: centralise links to blogs the interns write, either on Jupyter blog or their own
• maybe an Outreachy team on the JupyterHub page

[sgibson91]

I setup all the sphinx and readthedocs framework and we now have a site here: https://jupyterhub-outreachy.readthedocs.io/

"All" that's left to do, is populate it with info!

[sgibson91]

This issue will be closed when #183 is merged.

Follow up issues to complete the docs are:

• Docs: Add a reference section #174
• Docs: Update homepage #176