Annual Zenodo deposit

[drjwbaker]

Reviving an old idea (see https://github.com/programminghistorian/jekyll/issues/531 and https://github.com/programminghistorian/jekyll/issues/417). Potential benefits:

• Creates a digital object with a DOI that readers/authors can cite when citing PH as a whole
• Creates a digital with a DOI that readers/authors can cite for deprecated lessons or previous versions of lessons.
• Can feed into revision of lessons policy https://github.com/programminghistorian/jekyll/issues/498 For example, when substantial changes is made to a lesson the latest Zenodo dump can be cited at the head of the lesson so that someone looking for a previous version can find it.
• If we don't make a fancy, typeset pdf (like the 2016 dump that @acrymble made https://zenodo.org/record/49873#.Wa_ht4qQycY), this doesn't take much effort due to the Zenodo/GitHub interoperability.
• Zenodo is hosted by CERN so I trust it.

Tasks:

• Decide if we want to do this (to discuss at next Editorial Meeting, date TBC).
• Fit it into existing policies (eg, lesson revision and deprecation)
• Decide when to do it each year.
• Create a reminder to do it each year.
• Do it!

[arojascastro]

Maybe we can have a look at https://github.com/sx-archipelagos/sxa - they are publishing articles with DOI and creating PDF versions with ConTeXt.

[walshbr]

As per #596 @drjwbaker will take a look at drafting some language for a policy for this that would fit in the editorial guidelines for discussion.

[drjwbaker]

Draft Policy on making a regular citeable export of The Programming Historian

Why

Making a regular citeable export of The Programming Historian has two clear benefits:

• It creates a digital object that readers can use to cite The Programming Historian as a project.

• It creates a digital object that PH authors/editors can use to refer to archived lessons or previous versions of lessons.

• Scenario 1: an author wants to cite a lesson they wrote that has now been archived. It last appeared in the live version of the programming historian in 2017. They cite the 2017 PH export

• Scenario 2: a historian is writing an essay and wants to cite the work of PH. They use the latest PH export as their citation

• Scenario 3: PH makes substantial changes to a lesson. We change the lesson header to alert readers to this. We cite the latest PH export so that readers needing cite old version of the lesson can do so

What

At a high level I propose the following:

• That we export to Zenodo because it is trusted and enables us to create a DOI for the export.
• That we review the use of Zenodo annually.
• That we use the Zenodo-Github interoperability https://guides.github.com/activities/citable-code/ to create each digital object.
• That we export annually.
• That we export in December each year (starting 2017).

How

I will take on responsibility for managing the annual export. The export process will work as follows:

• Review the use of Zenodo (does it fulfill our needs per why/what above?)
• One month prior to export, notify team of planned export via a GitHub issue.
• Follow https://guides.github.com/activities/citable-code/ to create the draft export (we may need to create a new Zenodo account to do this)
• Create metadata. List all editors during the last calendar year as authors.
• Adapt the language from https://zenodo.org/record/49873#.Wc5Qd4prycY and https://zenodo.org/record/30935#.Wc5QeoprycY to create a README document that includes: all editors in the last calendar year; the mission statement at the time of export (from PH front page, both EN and ES versions); number of live lessons per category at time of export; names of all authors of live lessons at time of export; link back to PH.
• Present draft export to editorial team for review.
• Publish.
• Add to Twitter bot.
• Update 'Cite the Project' section of PH website (see Additional Actions below)

Additional actions:

Some other things that need to happen to make this work:

• We need a 'Cite the Project' section at https://programminghistorian.org/about (comparable to https://www.oldbaileyonline.org/static/Legal-info.jsp#citingproject) that lists the latest Zenodo export citation (and links to previous exports)
• I need comments/review of the above please :)

[acrymble]

We had some very strong objections to a 'Cite the Project' recently from within the team: #404

[drjwbaker]

Wow. Okay. I always look for 'Cite the Project' bits when I want to cite a project. I would of thought having a standard style helps project owners better understand how their project is being used/talked about because some readers will use the suggested citation. But if you've argued about this already, I don't want to rock the boat.

[acrymble]

I think it was a culture of higher education thing. I find them incredibly useful too. I've never managed to convince someone in North America though.

[ianmilligan1]

This all looks great @drjwbaker – consider this a vote. As for citing, I think Fred's comments were also getting at some of the difficulties of having a canonical citation for Programming Historian itself.. our editorial team changes, etc. etc., so it's hard to have a right citation for a given time. And it's also unclear whether it should be cited like a journal (where we don't list all the editors) or an edited collection, where they're more important.

Some of the issues around changing editorial teams could be handled by having the annual export though, maybe?

[acrymble]

@ianmilligan1 I think you're right about the journal vs collection. Either way I agree the Zenodo dump (which maybe we can give a nicer sounding name) is a great step in the right direction.

[mdlincoln]

@drjwbaker where do you suggest we display the list of versions on the website? (I'd suggest somewhere on https://programminghistorian.org/about - as @ianmilligan1 notes, it may be prudent to also link to https://programminghistorian.org/project-team#project-team-membership-history)

[drjwbaker]

Yes, the about page.

[drjwbaker]

Add latest citation under 'Open Source' at https://programminghistorian.org/about

[drjwbaker]

• [x] check I can make a Zenodo dump (using https://guides.github.com/activities/citable-code/ process)
• [x] make a release of the Jekyll repo
• [x] find a place to link the dump on main PH page
• [x] make a dummy dump
• [x] document service integration https://github.com/programminghistorian/jekyll/issues/595#issuecomment-340125178
• [ ] edit my bio to reflect that I manage this process

[acrymble]

Sorry I just thought of this, but I like the CHNM 'annual report' (https://rrchnm.org/news/annual-report-2016-2017/), and I think we should include something equivalent in this 'dump' (which sounds hasty and a bit messy) as a way of offering a nicely formatted changelog of sorts, and some built-in documentation for year-upon-year.

[drjwbaker]

@acrymble Okay. This is a bigger piece of work. Can you open a separate issues into which this will feed? I can then keep this issue for the technical/implementation side of the Zenodo dump.

[acrymble]

Sure. Can we call it a 'deposit' rather than a 'dump'?

[mdlincoln]

@drjwbaker you would also need to document this additional service integration at https://github.com/programminghistorian/jekyll/wiki/Service-Integrations

[drjwbaker]

I need to be an admin on https://github.com/programminghistorian/jekyll to make the Zenodo deposit work. I can see https://github.com/programminghistorian/ph-submissions via my Zenodo account, so I guess I need whatever settings I have there. Can someone take a look for me please?

[jerielizabeth]

Hi James, since you have two factor enabled (whoot!), I added you to the owners group. You should now have the necessary privileges.

@mdlincoln I hope I'm not stepping on any toes making the change :)

[drjwbaker]

@jerielizabeth Ta! (whoot indeed for two factor!)

[drjwbaker]

Okay. First step is to make a release of the jekyll repo. I've drafted this here https://github.com/programminghistorian/jekyll/releases/tag/untagged-d8690b3457b9c2542369 More info will be added once the Zenodo deposit is created. Please give a few thumbs up and I'll proceed to make the release live (or comment if you have comments).

[ianmilligan1]

My mobile interface doesn’t allow for reactions so consider this my 👍.

[acrymble]

Are you choosing a particular day of the year to do the release?

[drjwbaker]

@acrymble Hadn't planned to. Seems a little too precise. Would you prefer I did?

[ianmilligan1]

I think particular day of the year gets a little zanily precise (and then one day we'll have to worry about doing it on a Sunday or something). Why don't we just ballpark early November?

[drjwbaker]

That was my plan.

[drjwbaker]

Right. This is what it looks like raw out of the GitHub release doi.org/10.5281/zenodo.1046738

What I propose to do is:

• change the title to 2017 Programming Historian Deposit
• change the list of authors to all those who have edited PH in 2017
• change the upload type (the badge at the top) from Software to Lesson (other relevant potential options are: Publication or 'Other)
• change the description to:

This deposit contains materials for the Jekyll-based static site for The Programming Historian. The Programming Historian publishes novice-friendly, peer-reviewed tutorials that help humanists learn a wide range of digital tools, techniques, and workflows to facilitate research and teaching. We are committed to fostering a diverse and inclusive community of editors, writers, and readers.

At the time of deposit, The Programming Historians hosts 67 lessons. To date in 2017 we published FIXME new lessons and retired FIXME existing lessons

This deposit provides a citation for the project as it stands in November 2017. It is not intended to replace the Programming Historian website. This is the first annual deposit.

(who has numbers on lessons added and retired?)

[acrymble]

I think 'publication' might make more sense than 'lesson'. There's extra packaging around it that I think makes it a publication.

I'd also reduce the prominence of the 'jekyll-based static site', since it's the Programming Historian that we want to foreground.

We have 11 new lessons. 3 retired. Don't forget we have 28 Spanish language lessons!

Can you link somewhere to the earlier deposit I made a few years ago, just to create a chain? https://zenodo.org/record/49873

Otherwise, looks great.

[acrymble]

Also on the Zenodo page, some of the people's names are usernames rather than human names. Can that be changed?

[drjwbaker]

Thanks Adam. Updated https://doi.org/10.5281/zenodo.1046738.

[drjwbaker]

PR for deposit wording on cite https://github.com/programminghistorian/jekyll/pull/653

[drjwbaker]

In the call, someone said I should edit my bio to reflect that I do this. Where did they mean? The little button under my name at https://programminghistorian.org/project-team? (and if so, no idea how to edit that)

[walshbr]

@drjwbaker - has been a while but I think that was @acrymble who suggested in the call, and I think you're right. That was the part of the bio that I thought was being suggested. Others can correct if I'm wrong, but looks like the two files that you would modify for that are here and here:

https://github.com/programminghistorian/jekyll/blob/gh-pages/_data/ph_authors.yml https://github.com/programminghistorian/jekyll/blob/gh-pages/_data/teamroles.yml

You'd be adding a new team role (archivist? zenodo curator? something else?) in teamroles.yml and then giving yourself that role by modifying your entry in ph_authors.yml. It'd need to be translated as well.

[walshbr]

Discussed this briefly at #644 with who we had, @drjwbaker. No objections from me, @mdlincoln, or @amandavisconti. We say go forth.

[drjwbaker]

Awesome! PRs raised on the role thing: https://github.com/programminghistorian/jekyll/pull/664 https://github.com/programminghistorian/jekyll/pull/663

Closing this. Note: I've set a reminder to me to do this annually.