Instructor Notes

Lesson Overview

This lesson teaches researchers how to make software citable and discoverable. The core arc is:

Sharing → License → CITATION.cff → Release/DOI → Metadata

The environment management episode (pixi) is optional and sits after the release/DOI episode in the default lesson order. Decide before your workshop which track you are running.

Presentation Slides

A conference-style slide deck of this material exists as a separate artifact from the hands-on lesson. It was delivered at UC Love Data Week 2026 and is the right starting point for a short, talk-based version of this content.

The deck and this lesson are maintained independently. The slides are the canonical delivery artifact (designed in PowerPoint); the episodes are the canonical hands-on workbook. Earlier draft slide material (Marp, scripts, asset captures) is archived under dev/slide_assets/ (kept out of the built site) and is not maintained.

Reading the Room: Researchers vs. Support Staff

This lesson serves two overlapping audiences: people who write research software, and the library / OSPO / research-support staff who advise them. In practice your room will often be a mix, and sometimes it will be mostly researchers even when the workshop was billed for librarians. Plan to flex the framing live rather than committing to one persona.

The hands-on body is audience-neutral. The keystrokes to add a license, a CITATION.cff, or a Zenodo DOI are the same no matter who runs them. The audience-specific layer lives in two places:

  • “Supporting others” callouts in each episode are learner-facing asides that recast the technical step as advising and consultation work. If your room is mostly support staff, slow down and discuss these: ask “who on your campus owns this step, and when would you refer it out?” If your room is mostly researchers, read past them quickly or skip them.
  • These instructor notes are the meta layer for you.

Prompts that work well with a support-staff audience:

  • After the license episode: “A faculty member asks ‘can I just put MIT on this?’ What do you check before answering?” (Who owns the code, any third-party dependencies, and whether this is a referral to tech transfer.)
  • After the CITATION.cff episode: “Would you author this file for them, or coach them to do it? Where is the line?”
  • After the release/DOI episode: “Which DOI goes in their methods section, the version DOI or the concept DOI?”

If your audience is purely researchers, treat the “Supporting others” boxes as optional enrichment and keep the focus on their own repositories.

Two objectives per episode

Each episode lists a Supporting others objective alongside the hands-on one. The hands-on objective is “can you do this step”; the supporting objective is “can you advise, teach, or triage it for someone else.” With a support-staff audience, hold learners to the second objective too, not just task completion. The “Build your campus playbook” challenge in the wrap-up is where that second objective gets produced as a take-home artifact, so leave time for it.

Predict-then-reveal

Seeded Predict challenges (e.g., “what will GitHub do when you commit CITATION.cff?”, “what happens when you publish a release to a connected Zenodo?”) ask learners to commit to an answer before the reveal. This is the cheapest way to keep active-learning value when you are short on time or running a slide-based version: even without hands-on doing, a prediction plus a reveal keeps learners engaged. In slide mode, turn each demo step into a prediction first. Aim for one every 5 to 10 minutes.

Choosing a Track

Episode timings sum to about 3.25 hours for the citation-focused track and 3.75 hours for the full track. These are content minutes (teaching + exercises); add breaks, setup, and Q&A to get wall-clock time, so budget a half day either way. The per-episode teaching/exercises values are a starting point calibrated against mature Carpentries lessons; adjust them after your first run.

Full track (~3.75 hours)

All episodes in order, including the optional pixi episode at the end. Suitable when reproducibility and environment management are part of the workshop goals, or when your audience includes researchers who maintain code others need to run.

Citation-focused track (~3.25 hours)

Skip the pixi episode entirely. Suitable when learners just want their code cited, not necessarily reproduced. The FAIR4RS checklist in the wrap-up still works; omit the environment/interoperability row or note it as “future work.”

Set up: teach from your own fork

The whole lesson runs in the browser on a fork of UC-OSPO-Network/software-demo. Set yourself up exactly the way learners do, so you and the room share the same starting state and the same clicks.

Before the workshop:

  1. Fork UC-OSPO-Network/software-demo to your own account (or a throwaway teaching account). The main-only default is fine.
  2. Confirm your fork’s main is the bare starting state: README.md, requirements.txt, and src/analysis.py, with no license, citation, release, or metadata.
  3. Have the upstream repo open in a second browser tab so you can show the after-* reference branches on demand.
  4. If you’re teaching the full (pixi) track, also clone your fork locally and confirm pixi --version.

During the workshop, demonstrate each step live in your fork and let learners mirror it in theirs. Everyone commits to their own main. Because you forked the same starting state, your screen and theirs stay in sync.

Use a fresh fork for each teaching. Delete and re-fork (or reset) between workshops so you always start from the bare state, not last session’s finished repo.

The reference branches

The upstream repository keeps view-only reference branches showing the target state after each episode. Learners never build on them; they’re an answer key and a catch-up aid.

Reference branch State it shows
main starting state (what everyone forks)
after-license after Episode 2 (license added)
after-citation after Episode 3 (CITATION.cff added)
after-release after Episode 4 (release + DOI)
after-metadata after Episode 5 (full metadata, the finished repo)
optional-pixi the optional pixi episode (branches off after-metadata)

Why there’s no per-episode “check out this branch” step anymore. In the old command-line version, learners git checkouted a branch to teleport their working state forward when they fell behind. The web workflow has no equivalent, and it doesn’t need one: each episode adds an independent file (license, then citation, then release, then metadata), so a learner who misses one is never blocked, just less complete. To catch up, they open the relevant reference branch upstream and copy the one file they’re missing into their own main. Point this out once, early, then let the reference branches sit in the background.

Pixi is out of the main chain. Unlike the old demo repo, the after-* branches contain no pixi files. Pixi lives only on optional-pixi, which branches off after-metadata. So learners on the citation-focused track never see stray pixi.toml/pixi.lock files, and there’s nothing to explain away.

Common Sticking Points

GitHub “Cite this repository” button not appearing Learners need to commit the CITATION.cff file to the default branch and refresh. GitHub may take a minute to parse it. If it doesn’t appear, check that the file is in the root of the repository and named exactly CITATION.cff.

Zenodo Sandbox login Use sandbox.zenodo.org, not the real zenodo.org. Learners who accidentally create records on the live site cannot delete them. Warn the group before this step.

YAML indentation errors in CITATION.cff Direct learners to the cffinit web tool (https://citation-file-format.github.io/cffinit/) rather than hand-editing YAML. This eliminates most formatting errors.

Pixi not installed Pixi is optional and learners do not need it installed to complete the citation-focused track. If running the full track, verify pixi installation during setup. The pixi episode callout already marks it optional so learners who skip it can rejoin cleanly.

Introduction: Software as a Citable Research Output

Instructor Note

Why this framing works with researchers: they do not adopt these practices because they are virtuous. They adopt them because journals are starting to require citable code deposits, because funders ask, and because a DOI turns invisible labor into a countable, citable output for their CV. Lead with that: this is credit they are currently leaving on the table.


Instructor Note

Most librarians and support staff in the room will not have hit this exact error themselves, so don’t lean on it as a shared war story. Frame it instead as the barrier researchers describe when code “doesn’t work,” and flag that the mechanics live in the optional pixi episode, so a citation-focused workshop can acknowledge the problem and move on.


Keep FAIR4RS light here

Treat this as a preview, not a lecture. Learners will understand Findable, Accessible, Interoperable, and Reusable much better after they create the license, citation metadata, DOI, and README metadata. Name the four principles, point ahead to where each gets built, and move on.


Sharing Research Software Effectively

Instructor Note

Why this episode matters to researchers: reviewers now ask “where is the code,” and a bare repo is a worse answer than it looks, because it invites follow-up questions it cannot answer. The four-question triage below is also your own take-home tool; it is the five-minute consultation format the whole lesson builds toward.


Preparing to teach this episode

Teach from your own fork of the demo repository, exactly as learners do, so everyone is looking at the same starting state. See the Instructor Notes for the one-time fork setup. During the lesson you demonstrate each step live in your fork’s web interface and learners mirror it in theirs.

To show the “before and after” contrast, use the branch dropdown in the browser:

Use progressive disclosure: show only the top-level file listing first, then open individual files as you discuss them. No terminal or git checkout is needed; the reference branches are there to view and compare against, not to build on.


Confirm everyone is in their own fork

Before learners begin, ask everyone to confirm the top-left repository path says THEIR-USERNAME/software-demo, not UC-OSPO-Network/software-demo. Have helpers check Zoom/chat/room for anyone still on the upstream repository. Do not continue until most learners are in their own fork.


First status check

Ask learners to confirm they can see exactly README.md, requirements.txt, and src/analysis.py in their fork. This is the best early moment to catch learners who are on the wrong repository, wrong branch, or not signed in.


Choosing an Open-Source License

Instructor Note

Why this episode matters to researchers: licensing is where reuse and credit actually begin. An unlicensed repo cannot be legally built on, which means it will not accumulate the users, forks, and citations that make software count as a scholarly contribution. This is also the one episode with a hard referral boundary: you can explain categories and point to the campus default, but ownership questions go to Tech Transfer. Knowing where that line sits is itself the expertise.


Instructor Note

The decision guide below and the license references in this episode center UC policy and the UC OSPO guidance. For a non-UC workshop, swap in your own institution’s license guidance and name the local office that answers ownership questions (usually a technology transfer or research office) in place of the UC pointers.

Timebox the license discussion. The teaching target is not license philosophy; it is recognizing no-license risk, choosing a low-risk default for the demo, and knowing when to refer ownership or policy questions to Tech Transfer or the local equivalent. If the room starts debating MIT vs BSD, name the campus default and move on.


Expected UI state: the license template chooser

When the filename is LICENSE, GitHub should offer a license template chooser (“Choose a license template”). If learners do not see it, check the filename, that they are creating the file in the repository root, and a browser refresh before troubleshooting anything more complex.


Adding a CITATION.cff File

Instructor Note

Show learners what the citation panel looks like on a GitHub repository that already has a CITATION.cff file. This gives them a clear target and reduces cognitive load.

Reassure learners that a tiny file is fine. They can refine it later as their software matures.

Why this episode matters to researchers: this is the single highest-return step in the lesson. One small file, committed once, and every future citation of the software is correct, complete, and countable. It is also the step where a scholcomm professional can sit beside a researcher as the expert, because the hard part is metadata judgment, not code.


Common stall: perfecting authorship

Learners may try to perfect authorship, contributor roles, or author order. For the demo, use the provided values and keep moving. For real projects, authorship order is a PI/team decision; the consultant can explain the fields and options but should not decide credit. If someone asks “who counts as an author?”, flag it as a team conversation, not a metadata fix.


YAML recovery path

If more than a few learners hit YAML indentation errors, switch the whole room to cffinit rather than debugging individual whitespace mistakes. The goal is citation metadata, not YAML mastery. cffinit validates as they type and produces a file they can paste.


Predict, then reveal

Before learners refresh GitHub after committing CITATION.cff, ask them to predict what GitHub will add. Then reveal the “Cite this repository” panel. This keeps GitHub’s helper behavior visible as a platform pattern rather than a surprise, and sets up the “GitHub recognizes certain filenames” idea later.


Making Your Software Citable

Instructor Note

Some learners may feel anxious about creating a DOI.
Reassure them that:

  • a DOI is not required for citability
  • Zenodo is free and widely used
  • they can watch the demo and complete the steps later

Why this episode matters to researchers: this is where journal and funder requirements actually bite. “The journal wants a citable code deposit” means, concretely, a tagged release with a DOI, and after this episode you can say that sentence and demonstrate the twenty-minute path to compliance. The DOI is also the moment their software starts accruing countable citations, the currency their review committees already understand.


Say this out loud before you screen share

Use sandbox.zenodo.org, not production Zenodo. Real Zenodo records and DOIs are persistent and cannot be deleted, so they are not appropriate for practice. Say it before you share your screen, and have helpers watch for learners who land on zenodo.org by habit.


Do not rush the snapshot idea

This point is subtle and important, so slow down. Say: “GitHub is the live working copy; Zenodo archived what existed at release time.” Then ask a learner to restate, in their own words, the difference between a post-release GitHub edit and the already-archived release snapshot. If they can restate it, they have the key mental model of the episode.


Debrief prompt for support-staff learners

Once the DOI appears, ask: “Which DOI would you tell the researcher to put in the methods section, the version DOI or the concept DOI, and why?” Expected answer: the version DOI for exact reproducibility (the state that produced the results); the concept DOI to refer to the project in general. This turns the mechanic into an advising decision they will actually be asked to make.


Improving Metadata and Discoverability

Pacing: what is hands-on if you are short on time

Make README improvements and GitHub topics the hands-on work here. Treat .zenodo.json, Software Heritage, CONTRIBUTING.md, and CODE_OF_CONDUCT.md as instructor demo or optional reading. In a half-day workshop, do not make every extension a hands-on task; it is the fastest way to run out of time before the wrap-up.


Instructor Note

Encourage learners to compare well-described repositories with sparse ones.
Highlight how even small metadata additions increase visibility in GitHub search, Zenodo indexing, and DataCite services.

Why this episode matters: this is where a librarian in the room can visibly outperform the researchers, which matters for how the campus sees the service. Researchers usually treat metadata as a form to rush through; a scholcomm professional treats it as the mechanism of discovery. The pitch to the researcher is blunt: the work is finished, and five minutes of description determines whether anyone ever finds it.


Frame .zenodo.json as advanced

Do not present .zenodo.json as required for all projects. Frame it as an advanced override, used only when Zenodo metadata needs more control than CITATION.cff provides. Most learners should leave with CITATION.cff as their one citation file.


Managing Reproducible Environments with pixi

Take a hard fork here

Citation-focused learners are done with the core lesson after the metadata episode; send them off or into a break. Only full-track learners continue, and they need a local clone and pixi installed. Do not make the whole room troubleshoot installations. State clearly who this episode is for before anyone opens a terminal.


Teaching this optional episode

This episode is last in the lesson order and is the only one that leaves the browser: it needs pixi and a terminal on the learner’s own machine, plus a local clone of their fork. Because the rest of the lesson is browser-only, confirm during setup which learners are prepared for the full track. Anyone who only wants their code cited can stop after the metadata episode with a complete, citable repository.

The optional-pixi reference branch builds on after-metadata, so it shows pixi added to an already-finished project. Have learners view it in the browser for the target pixi.toml and lockfile, then work along in their local clone. Nothing in the main project chain depends on pixi, so skipping this episode leaves no loose ends in anyone’s repository.

Pixi not installed? Learners can follow the concepts without a working pixi installation. The key idea is that a lockfile pins exact dependency versions. That’s the transferable lesson, not the tool itself.

If you skip the hands-on entirely, keep the concept in the room: the R in FAIR quietly depends on this. A deposit that cannot be executed is preserved the way a locked diary is preserved. The question “is there a record of what this needs to run” belongs in the consultation checklist even if the mechanics get referred to research computing.


Assign a helper to install issues

If you are teaching the full track, assign one helper to pixi install and PATH problems. The lead instructor should keep moving with the concept demo and not stop the main room for individual terminal errors. Installation issues are the single most likely time-sink in this episode.


Wrap-Up and Reflection

Instructor Note

Give learners a few minutes of quiet reflection, then facilitate a group discussion. Invite volunteers to share a step they plan to take next.

Closing pitch worth saying out loud: for instructors, the deliverable is not the demo repo, it is a service, a consultation format and a referral map usable the week you get home. For researchers, it is a repeatable habit that costs under an hour per project: every future paper’s code can either be a dead URL in five years or a citable, findable output on your record, and the difference is the checklist you now hold.


Make it a local service map

Have each support-staff learner write down one campus referral they still need to identify after the workshop: Tech Transfer, research computing, the data repository, information security, the grants office, or scholarly communications. Naming a real gap turns the demo into a local service map they can actually use on Monday.