Improving Metadata and Discoverability

Findability comes from description

A Zenodo record with a bare title and no keywords is a catalog record with no subject headings: retrievable if you already know it exists, invisible if you don’t.

The tools are GitHub topics, Zenodo fields, and a README. The question is the same: what would a seeker search for, and does this record contain it?

You already have a license, a CITATION.cff, and a DOI. This episode ties them together.

PRE-FLIGHT (before you take over) Open these tabs, in this order:

Your prepared repo: github.com/jt14den/software-demo-prepared (already has LICENSE, CITATION.cff, and a release with a Sandbox DOI)
Upstream 05-add-metadata: github.com/UC-OSPO-Network/software-demo/tree/05-add-metadata
Your prepared repo’s Zenodo Sandbox record: sandbox.zenodo.org/records/607977 (DOI 10.5072/zenodo.607977; your YOUR-RECORD-ID for the README demo is 607977)
The Etherpad, with the starter README already pasted

~2 min · SHOW: slides only.

SAY: I’m switching to a copy I prepared earlier, at the same point your fork should be after Reid’s episode, so you’re not waiting on me. The work is finished, and five minutes of description decides whether anyone ever finds it. Libraries already know how to do this: it’s cataloging.

What counts as useful metadata?

Good metadata answers predictable questions with minimal effort from the reader:

What is this software? A short description or abstract
Who made it? Authors and ORCIDs
How do I cite it? CITATION.cff and a DOI
What field is it for? Keywords
What else does it relate to? A related article, dataset, or funder

Add GitHub Topics

On your repo’s front page, click the gear icon next to About, then fill in Topics:

Discipline: geospatial, text-mining, materials-science
Method: simulation, visualization, machine-learning
Language: python, r

The 30-second rule

Your README is your software’s front door.

If people can’t tell what it does, how to install it, and how to use it in 30 seconds, they leave.

A repo without a real README is a collection without a finding aid: only its author can use it.

README: 7 essential sections

About: what it does, in 2-3 sentences
Features: key capabilities
Getting Started: prerequisites and install
Usage: a minimal working example

Citation: link to CITATION.cff or the DOI
License: state the terms
Contact: how to get help

UC OSPO README Guide (UC-specific)

Challenge: give your README the 7 sections

⏱ 5 min

In your fork of software-demo:

Open README.md and click the pencil icon to edit
Add a ## heading for each of the 7 sections: About, Features, Getting Started, Usage, Citation, License, Contact
Fill in what you can, then Commit changes to main

Short on time? Keep your title and DOI badge, replace everything below them with the starter README from the Etherpad, then replace YOUR-USERNAME, YOUR-DOI, and YOUR-RECORD-ID (from your Sandbox record’s web address).

Next: compare yours with the reference README.

~6 min · 1-minute demo, then 5 minutes for learners

BEFORE: check the starter README is in the Etherpad.

DO in your prepared repo (tab 1): https://github.com/jt14den/software-demo-prepared

Click README.md, then the pencil icon (or go straight to https://github.com/jt14den/software-demo-prepared/edit/main/README.md)
Keep the title and the DOI badge line. Delete everything below them
Paste the starter README from the Etherpad
Fill in the three placeholders (values from your Sandbox record, https://sandbox.zenodo.org/records/607977): YOUR-USERNAME → jt14den, YOUR-DOI → 10.5072/zenodo.607977, YOUR-RECORD-ID → 607977
Click Preview: the headings render, and the LICENSE, CITATION.cff, DOI, and issue links work
Click Commit changes…, then Commit changes again (straight to main)

SHOW: the front page with the new README: https://github.com/jt14den/software-demo-prepared

SAY: Your turn, 5 minutes. Use the starter or write your own. Your DOI and record number are on your Sandbox record from Reid’s episode.

Start the timer. When it ends, click once to show the “Next” line, then advance.

HELPERS, common problems:

Editing the upstream repo, not their fork: check the owner name at the top of the page
##Heading with no space: add a space after ##
Never clicked Commit: nothing changes on the front page
DOI link won’t open: Sandbox DOIs don’t work on doi.org, which is why the starter links to the Sandbox record
No DOI badge: copy the badge Markdown from their Sandbox record and paste it under the title

Before → after

❌ Before (main, starting state)

# Biodiversity Analysis Toolkit

Analysis tools for biodiversity
research data.

One line of description. No install steps, no usage, no citation, no license, no one to contact.

✅ After (05-add-metadata, abridged)

# Biodiversity Analysis Toolkit
[DOI badge] [License badge]
Analysis tools for biodiversity...   <!-- 1 About -->

## Features                          <!-- 2 -->
- Citable, open source, documented

## Getting Started                   <!-- 3 -->
Prerequisites: Python 3.9+
### Installation & Usage             <!-- 4 -->
pip install -r requirements.txt
python src/analysis.py

## Citation                          <!-- 5 -->
Cite via CITATION.cff or the DOI badge.
## License                           <!-- 6 -->
BSD 3-Clause. See LICENSE.
## Contact                           <!-- 7 -->
Open an issue in this repository.

Beyond the README: community health files

CONTRIBUTING.md
How to contribute. Add one if you want contributions, or say plainly that you don’t.

CODE_OF_CONDUCT.md
Behavioral standards. Contributor Covenant is the standard choice.

CHANGELOG.md
Version history: what’s new, what broke, what changed.

GitHub recognizes certain filenames

File	What GitHub does
`README.md`	Renders as the repository’s landing page
`LICENSE`	Shows the license in the repo sidebar
`CITATION.cff`	Adds “Cite this repository” with APA/BibTeX
`CODE_OF_CONDUCT.md`	Counts toward the community profile
`CONTRIBUTING.md`	Links guidelines when someone opens an issue/PR
`SECURITY.md`	Becomes the security policy

These only appear once the file is on the default branch. GitHub changes the details, so teach the pattern: the filename is the signal.

Where should software live?

Zenodo is the recommended deposit location for software:

Archives each GitHub release automatically
Mints a DOI for every version
Registers records with DataCite, which discovery services harvest
Free, run by CERN, recognized by journals and funders

Dataverse and Dryad are good for datasets, but don’t auto-integrate with GitHub releases the same way.

UC-specific: all UC campuses have Dryad. If you deposit data there, Dryad prompts a linked Zenodo code deposit automatically.

Zenodo metadata is what discovery systems see

Zenodo registers each record with DataCite. Search tools and discovery services pick it up from there, so the Zenodo record is what they show.

Add or refine: authors + ORCIDs, keywords, related works, funding, a readable description.

Caution: if a repo has a .zenodo.json, Zenodo uses that file, not CITATION.cff. Keep them in sync or you’ll publish two different citation records for the same software.

Supporting others: priority order when metadata is thin

A readable description, the biggest loss when it’s missing
Author ORCIDs: without them, every J. Chen on Zenodo looks the same
Keywords, reused consistently across GitHub, CITATION.cff, Zenodo
Related works: link the software to its paper, dataset, and grant

Challenge: improve your Zenodo record

⏱ 5 min

Open your record on Zenodo Sandbox (sandbox.zenodo.org) from the release episode. Select Edit, and add:

keywords
author ORCIDs, if they’re missing
a real description
optional: a related paper or funder, if you have one

Save and publish the updated record when done.

~6 min · DEMO for 1 minute, then 5 minutes for learners. Start a 5-minute timer.

DO in tab 3, your Sandbox record: https://sandbox.zenodo.org/records/607977

Click Edit (on the right side of the record page)
Keywords: add biodiversity, research-software, python (same words as your topics)
Creators: point at your ORCID. It’s already there because CITATION.cff carried it into Zenodo, which is why Laura’s episode matters. Learners whose CITATION.cff had no ORCID add theirs here
Description: paste your README’s About paragraph
Save draft, then Publish

SHOW: the updated record.

SAY: Editing metadata doesn’t mint a new DOI. The same DOI now has a better record.

HELPERS: watch for anyone on zenodo.org instead of sandbox.zenodo.org. Anyone whose release didn’t reach Zenodo in Reid’s episode has no record: they watch your screen, and helpers note who’s stuck.

Challenge: which change makes it discoverable?

⏱ 3 min

A tool has been public on GitHub for a year: one-line README, no topics, a Zenodo record with only a title. Which single change matters most?

A. Add collaborators
B. Descriptive topics, matching keywords, and a description
C. More frequent commits
D. A shorter name

B. People find software through its description. Commit activity doesn’t help. It’s the same reason a catalog record with no subject headings is nearly invisible.

Key points

Description is what makes software findable, on GitHub, Zenodo, and beyond
Use the same title, names, and description in CITATION.cff, README, topics, and Zenodo

Get involved

Join

Slack: day-to-day questions and resources
Newsletter: sign up from the Contact page
Your campus mailing list: also on the Contact page

Show up

All-campus virtual meetup: first Thursday of each month, 10am
Coworking & office hours: Tuesdays 10am, Thursdays 1pm
UCSB Open Source Lounge: Thursdays 2:30-4:30pm, hybrid, open to all UC

Start here: ucospo.net/about/get-involved · Questions: Laura Langdon, Community Manager

All times Pacific. Zoom links and calendar feeds: ucospo.net/events