# CodeRefinery JOSE publication

> This is a publicationa on the full workshop, single lesson publications would be great to do as well, but different topic for later!

[TOC]

## Lessons

* Testing: https://doi.org/10.5281/zenodo.16410887
* Jupyter: https://doi.org/10.5281/zenodo.16410839
* Social coding: https://doi.org/10.5281/zenodo.16410766
* Reproducible research: https://doi.org/10.5281/zenodo.16410659
* Documentation: https://doi.org/10.5281/zenodo.8280234
* Modular code development: https://doi.org/10.5281/zenodo.16925149
* Git intro: https://doi.org/10.5281/zenodo.16925023
* Git collaborative: https://doi.org/10.5281/zenodo.16925120

## Guidelines

https://openjournals.readthedocs.io/en/jose/

### Requirements

- Have the content in an open repository, under a Creative Commons license (ideally CC-BY), and any code components under an OSI-approved license.
- Write a short Markdown file titled paper.md with title, author names and affiliations, containing a description of the module, a summary of its contents, a statement of need, and key references.
- References should be included in a BibTeX file called paper.bib

### Paper should include

JOSE papers should:

- [ ] List all authors and affiliations.
- [ ] Describe the submission, and explain its eligibility for JOSE.
- [ ] Include a “Statement of Need” section, explaining how the submitted artifacts contribute to computationally enabled teaching and learning, and describing how they might be adopted by others.
- [ ] For software submissions, describe the functionality of the software, usage and recent experience of use in teaching and learning situations.
- [ ] For learning modules, describe the learning objectives, content, instructional design, and experience of use in teaching and learning situations.
- [ ] Tell us the “story” of the project: how did it come to be?
- [ ] Cite key references, including a link to the open archive of the sofware or the learning module.

JOSE welcomes submissions with diverse educational contexts. You should write your paper for a non-specialist reader. Your submission should probably be around 1000 words max (or around two pages).

The goal is that someone reading the JOSE paper has enough information to decide if they’d be interested in adoping the learnig module or software. Readers will want to know how the content/software has been used, and how they would adopt it. They may also want to be persuaded that the authors have put careful work on creating the material, and have experience teaching with it.

## Paper content

General checklist:

- [ ] Installation instructions: Is there a clearly stated list of dependencies?
- [ ] Usage: Does the documentation explain how someone would adopt the module, and include examples of how to use it?
- [ ] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the module 2) Report issues or problems with the module 3) Seek support?
- [ ] Repository: Is the source code for this learning module available at the repository url?
- [ ] License: Does the repository contain a plain-text LICENSE file with the contents of a standard license? (OSI-approved for code, Creative Commons for content)
- [ ] Version: Does the release version given match the GitHub release (v1.0)?
- [ ] Authorship: Has the submitting author made visible contributions to the module? Does the full list of authors seem appropriate and complete?

### Authors and affiliations

- ..
- ..

### Description of submission + eligibility for JOSE

...

### Statement of Need

> A statement of need: Does the paper clearly state the need for this module and who the target audience is?

- link to audience on event page
- link to feedback
- link to impact: https://coderefinery.org/about/impact/

### Learning objectives

> Learning objectives: Does the module make the learning objectives plainly clear? (We don’t require explicitly written learning objectives; only that they be evident from content and design.)
...

Course goals (from event page):
In this course, you will become familiar with tools and good practices for scientific software development. This course will not teach a programming language, but we teach the tools you need to do programming well and avoid common inefficiency traps. The tools we teach are practically a requirement for any scientist who needs to write code. The main focus is on using Git for efficiently writing and maintaining research code.
This is not a course about a specific programming language or the Linux/Unix terminal shell. We assume that you are somehow familiar with the programming language that you use in your work and research. Most of the course applies to any programming language.

Learning objectives are listed for each lesson separately in the beginning.
- link to each lessons learning objectives + overview on event page

#### Prerequisites

- Summary of and link to : https://coderefinery.github.io/2025-09-09-workshop/requirements/

### Content

> Content scope and length: Is the content substantial for learning a given topic? Is the length of the module appropriate?
> Content quality: Is the writing of good quality, concise, engaging? Are the code components well crafted? Does the module seem complete?
...

The CodeRefinery workshop is set up to meet researchers where they are in their daily work after having learned how to program. Topics covered in the workshop (currently taught in 3 half days + 6 2-hour sessions):

* Version control with focus on collaboration and not only for the command line:
* Introduction to version control (day 1-2): Why we want to track versions and how to go back in time to a working version. This lesson brings you from zero to using Git and GitHub for own projects.
* Collaborative distributed version control (day 3): This lesson builds on "Introduction to version control" and we apply branching and learn about pull requests (merge requests), forks, and collaboration using Git and GitHub.
* Reproducible research (day 4): Preparing code to be usable by you and others in the future. We focus here on 3 aspects of reproducible programs and computations: documenting dependencies, environments, and computational steps in a reproducible way. We touch on containers.
* Social coding and open software (day 4): What can you do to get credit for your code and to allow reuse. We motivate and give an overview over software and data licensing and software citation best practices.
* How to document your research software (day 5): Here we give an overview of the different ways how a code project can be documented: from small projects to larger projects. Markdown and Sphinx are central tools in this lesson.
* Jupyter notebooks (day 5): A tool to write and share executable notebooks and data visualization. This lesson gives an overview of what Jupyter notebooks are, when they can be particularly useful, and shows best practices for reusable and reproducible notebooks.
* Automated testing (day 6): Preventing yourself and others from breaking your functioning code. In this lesson we talk about motivation for testing, about test design, but also about some tools that are typically used for automated testing of software.
* Modular code development type-along (day 6): Making reusing parts of your code easier. The focus of this lesson is how to partition and organize projects as they grow from one screen-full to larger and how to make code portions reusable across projects and across notebooks.

### Instructional design

> Pedagogy: Does the module seem easy to follow? Does it observe guidance on cognitive load? (working memory limits of 7 +/- 2 chunks of information)
> Instructional design: Is the instructional design deliberate and apparent? For example, exploit worked-example effects; effective multi-media use; low extraneous cognitive load.

The materials are provided as static websites built using Sphinx and GitHub actions from Markdown files. We use our own sphinx extension (link to sphinx lesson here). To accomodate learners with different tool preferences and preference for programming languages we have implemented tabs throughout the learning materials. In exercises, it provides learners with the opportunity to "choose their own adventure" based on preferences, but also provides a glimpse into potentially new worlds.
Each lesson inlcudes an instructor guide which varies in details. We also maintain a set of operation manuals for our workshops which can be found:

- Link to instructor guides of the lessons and manuals

#### Reuse and contribute

All of our material is open source and reuse is encouraged. In general, we only recommend similarly open-source, reusable lessons. Check the license from each repository in case of questions (most CodeRefinery-developed lessons use CC BY 4.0).

Our core lessons can also be cited and linked to via DOI (published in our Zenodo community :

* Git intro: https://doi.org/10.5281/zenodo.16925023
* Git collaborative: https://doi.org/10.5281/zenodo.16925120
* Reproducible research: https://doi.org/10.5281/zenodo.16410659
* Social coding: https://doi.org/10.5281/zenodo.16410766
* Documentation https://doi.org/10.5281/zenodo.8280234
* Jupyter: https://doi.org/10.5281/zenodo.16410839
* Testing: https://doi.org/10.5281/zenodo.16410887
* Modular code development: https://doi.org/10.5281/zenodo.16925149

Teaching these lessons independently is encouraged, just make sure the distinction between the "CodeRefinery" project and your workshop is clear. For example, give your own name to the workshop but say "(CodeRefinery lessons)".

Our lessons are designed to be generic, (mostly) stand-alone, and re-used in place without forking so that anyone can use them and they can fit into different types of programs. We welcome contributions which make the lessons more reusable - send changes using standard open-source practices (you know, what we teach in CodeRefinery and all).

### Experience of use in teaching and learning situations

This material and its predecessors has been used for XX in-person and XX online workshops (see https://coderefinery.org/workshops/past/). Many of the latest workshops have been recorded and videos are available on YouTube: https://www.youtube.com/@coderefinery . Some of the lessons also include field reports by the instructors from specific workshops as well as detailed planning documents for the teaching. For the workshops we collect daily feedback in our collaborative notes (see past events > event page > q&a > scroll to bottom of document). We also collect long term feedback via survey that is sent out to participants of our workshops minimum half a year after they attended the workshop, results of the last of those can be found in our blog: https://coderefinery.org/blog/2024/08/10/post-workshop-survey/.

### Story of how it came to be

> Does the paper tell the “story” of how the authors came to develop it, or what their expertise is?

- Something from https://coderefinery.org/blog/2024/09/19/celebrating-8-years/
...

### References

...