Explore making the tutorials citable

[adrn]

Either as a whole, or individually (get each tutorial a zenodo DOI when it is published?).

[emilylurice]

I think Guides should absolutely be individually citable, but tutorials ... probably also worth having individually citable.

…

On Sep 22, 2017, at 4:27 PM, Adrian Price-Whelan ***@***.***> wrote: Either as a whole, or individually (get each tutorial a zenodo DOI when it is published?). — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[pllim]

When a tutorial gets updated, does it retain the same DOI or get a new one? For example, if I cited a tutorial on Sep 21, and then it gets updated Sep 23 and its content changed in a non-backward compatible way, people reading my paper would be very confused.

[adrn]

The tutorials would have to be updated and re-published in a more formalized way. That is, the DOI would refer to a version of the tutorial. I'm not necessarily advocating for implementing that now, but it's something to think about.

[kelle]

Here's a lesson on this topic: https://reproducible-science-curriculum.github.io/publication-RR-Jupyter/aio.html
They recommend using nb_convert to output to a format and then upload. I think we could just output to a PDF and then upload to Zenodo. I think this is worth doing once the UW-Madison tutorials go live.

[adrn]

New proposal: since we are planning to release the tutorials with major releases of Astropy, we can set up Zenodo to create new records / DOIs for each release of the tutorials. The one thing we need to be careful of is to make sure that everyone who has contributed to the tutorials appears, because some people may not have commits in the repository. I'll set this up and release a v3.0 version soon!

[kelle]

look into making a Astropy user on Zenodo to be the owner of the records.

[pkgw]

Context is that Zenodo doesn't seem to have infrastructure for organizations in the same way as GitHub, so we think that any records created would be owned by some specific account, which would add a single point of failure if someone disappears.

The Dataverse project is similar to Zenodo in a lot of ways and seems that it does have support for group-administered sub-dataverses.

[kelle]

I think this should be a bit higher on our priority list. Any objections to making an Astropy Zenodo account? I'll bring up with Coordinators.

[keflavich]

bump! I want tutorials to be citable objects! (necessary for grants that don't accept URLs in the main text)

[kelle]

Hey @nstarman, your ideas about how to implement citation would be welcome here.

[kelle]

Update: we do indeed have a team Zenodo account.

[nstarman]

We were thinking alike, I also imagined citations would be managed by Zenodo, using their version management.
Zenodo also provides badges, which can be embedded, e.g. in the tutorials.
I'm not sure how we determine running authorship, as edits are made, but we can think up a good heuristic.

[pkgw]

I just wanted to jump in here on the authorship issue: it depends on what you mean by "heuristic", but think it's pretty important for a human to have control over the author list during the publication (deposition) process. Think of a standard journal article: membership on the author list is a big deal, and the "best" membership and ordering isn't necessarily something that a machine can determine algorithmically, in general. In my opinion, treating these author lists seriously contributes to the broader effort to ensure that non-traditional academic outputs are properly valued by the community.

(This is not to exclude the possibility that the humans might decide that the best author list is something collective like "The AstroPy Collaboration".)

Author lists for regularly-released artifacts like these tutorials can be a bit "harder" than those for journal articles because you might have to decide what do to about adding and removing authors as their contribution levels vary over the long run. But regardless of how those issues are handled, I think the underlying principle should be that determining the author list is an important task to be handled by, well, the authors.

[keflavich]

I'd like to bump this as an important community-wide issue. I'd like to encourage my students to produce tutorials, but I also want them to get some form of standard academic credit. Are we good to proceed with the zenodo approach? Can we make this official by pushing to zenodo upon merge into main? (Peter's comments about authorship are important too though).

Has anyone reached out to ADS about this? Can we have something parallel to ASCL, or can we use ASCL?

Part of the context of bumping this now is that we recently had a workshop at NRAO in which several of us encouraged the attendees to make more tutorials, following the learn.astropy.org model and https://radio-astro-tools.github.io/tutorials/, which is based on astropy-learn. I want to give this group more incentives to use our infrastructure and follow our path.

[pllim]

Zenodo is probably easiest, there are already instructions for APEs. Wouldn't be wise to try to roll "our own ASCL". If you want to collaborate with ASCL, try contact Alice Allen (https://ascl.net/home/getwp/899).

[kelle]

Now that we have an astropy.team Zenodo account, I think this is clearly the best way to go. Someone (@ceb8?) should probably open an issue (or multiple issues) in the Learn repo to upload the existing tutorials.

[kelle]

Once they are on Zenodo, we can send a list to ADS and I think they will index them if we ask nicely. @aaccomazzi?

[kelle]

@arm61 - We have a collection of notebooks which we would like to get proper DOIs for. Do you have any thoughts on a good way to do this? Maybe we submit each one to Journal of Open Source Education? Or should each JOSE submission be it's own repo?

[kelle]

Also tagging @labarba for her thoughts.

[arm61]

I want to defer to @labarba on this, but this could fit into the branch of "computational learning modules" as mentioned in the documentation for JOSE (https://openjournals.readthedocs.io/en/jose/submitting.html).

[labarba]

Could someone summarize what you want me to weigh in about? This thread is long and goes back 7 years!
From a quick browse of last comments: if you just want DOIs, you can upload to Zenodo. When to use JOSE instead? If you have a finished set of notebooks that form a workshop or minicourse that has some history of being used in a teaching setting, and you want a journal paper to cite the effort.

[jeffjennings]

Issue opened in learn-astropy repo to proceed with Zenodo.