overview of feedback and ideas

[nehamoopen]

PRE-WORKSHOP

• Read: Wilson G, Bryan J, Cranston K, Kitzes J, Nederbragt L, Teal TK (2017) Good enough practices in scientific computing. PLoS Comput Biol 13(6): e1005510. https://doi.org/10.1371/journal.pcbi.1005510
• Watch: UU GitHub video

** PREPARATION**

• remove recommendation for creating synthetic data
• embed Terminal video
• provide some Terminal commands
• review Git & GitHub sub-chapters

INTRODUCTION

• remove slides from the corona days, keep it simple

PROJECT SETUP

• Provide GitHub repository templates for simple R & Python projects. #43
• Discuss absolute vs. relative paths in more detail.
• Question: Should Python users already set up a virtual environment at this stage?
• the .gitkeep files should eventually be removed from the template?
• explore the template folder structure

VERSION CONTROL

• Adapt slides from Git for Humans presentation.
• Focus on the main commands for a single user: add, commit, push, pull, status, log.
• Point out UU GitHub organization.
• Point out integrations with IDEs.

CODE QUALITY

• Readability: https://stylish-code.netlify.app/#/

DOCUMENTATION

• Question: Any best practices or examples for headers/title/YAML for scripts?
• Adapt StackOverflow blogpost about best practices in commenting.
• Link to Make A README website + shields.io and other README resources/examples/generators.

REPRODUCIBILITY

• Include virtual environments for Python
• sessionInfo() for R users, there is also the groundhog and checkpoint packages which are more lightweight. Annotator add-in for RStudio is also useful.
• Question: Perhaps we could present options from lightweight/easy (declaring sessionInfo output in README and annotating library calls) -> middle-ground (using groundhog/checkpoint or code snippet to install missing packages) -> best practice (renv) -> advanced( Docker). Don't know how this would translate to Python.
• Question: Look into environment.yml and requirements.txt generation and ensure how to always get libraries for the current project and not all the libraries available locally (doesn't always work). Do we assume everyone has pip or anaconda installed? #44
• _Question:_Similar to previous two notes, figure out how renv really works and consider if it should be done at the beginning already and how to only get project packages and not system packages.

ARCHIVING & PUBLICATION

• Note that Zenodo integration with GitHub repo should be activated first (toggle on) before making a release else it won't get detected.
• Question: Talk about GH releases more? Talk about SemVer and CalVer?
• Include something about CFF files for citation.

ADDITIONAL

• Binder could be a demo.
• Reproducibility Check should be a chapter: provide the checklist or template
• What we don't cover, but could be interesting? chapter/section: automation with MAKE / batch files / shell scripts, scheduling things, working with Docker, CI/CD with GitHub Actions, working with dynamic documents...
• some things could be given as 'homework' like reading up on SemVer and CalVer or thinking about your README content..
• MATLAB users have been providing tips/links - these could be mentioned in the book somewhere. Also for STATA.

[nehamoopen]

additional discussion:

• the final exercise reproducing each other's projects, do we want to prioritize this or not? If yes, we need to give people more time for this (and previous exercises as well) so they can pull this off.

• we can shorten/demo things related to binder, archiving, publishing?

• explicit instructions on how to have Python (and maybe R) installed