Restructure and flesh out contributing guides: for authors and reviewers

[ateucher]

As discussed in coworking with @jules32 and @danielfromearth, we need to improve the contributing guide, for both authors and reviewers.

This is a draft of the structure/outline of the things we need to help contributors and reviewers:

• Guide for authors
  • Mechanics (git/github, using template, PR etc)
  • Content guidance:
    • This is a place I would write a spec or editorial doc that lists each heading, whether it’s required, and why
    • Scope
    • Required vs optional sections
    • Length
    • Style (code cells and markdown content)
    • Pedagogy
  • Meta: has it been taught/field-tested, does it run (local/hub)
• Guide for reviewers
• Templates:
  • How-to (.qmd and .ipynb)
  • Tutorial (.qmd and .ipynb)
• Github actions for PR checking:
  • Format (ruff, air)
  • Check for required sections (pre-commit?)
  • Run the notebook?

Things to consider:

• How to separate mechanics from content guidance? We don't want to scare away contributors with heavy, technical mechanics of git etc.
• Templates - include "Shining examples". Show don't tell

Resources:

• Preexisting material from Danny as a starting point:
  • https://github.com/nasa/ASDC_Data_and_User_Services
  • Custom markdown checker script (called by pre-commit)
  • Existing ASDC contributing guide
• Coworking session and discussion
• https://projectpythia.org/cookbook-guide.html - quite a heavy lift for new contributors
• https://book.the-turing-way.org/community-handbook/contributing-guideline#the-process-of-writing-chapters
• Posit resources:
  • Tidyverse code review principles: https://code-review.tidyverse.org/
  • Tidyverse style guide (R): https://style.tidyverse.org/
  • Advice on writing vignettes (from R Packages book): https://r-pkgs.org/vignettes.html#advice-on-writing-vignettes
• Jenny Bryan’s 3 rules for Naming Things:
  • machine readable
  • human readable
  • plays well with default ordering
  • Slides available from Speakerdeck. See also Jenny’s “Naming things” video (5 mins) from NormConf · Dec 4, 2022

Related pre-existing issues:

#238
#242
#120
#245

[jules32]

Let's also see if we can draw from/reuse/boost the GitHub+Quarto Contributing Clinic that Stef + Andy led in June 2024...