Software citation bis

[spapastamkou]

This is relevant to previous discussions in #1984 (and long due on my behalf) on how to cite software; I open the issue following a recent exchange with @anisa-hawes. While updating the FR author guidelines some months ago, I added further elements to the general pattern that had been agreed in the aforementioned issue. The additions were based on the recommendations of the Software Heritage Foundation and offer two more elements, "module" and "code fragment", plus licence, which are available in this bibliographical style and presented in this article. Here is how it goes in the FR guidelines:

"Pour citer un logiciel, suivant les recommandations du projet Software Heritage, merci de fournir toute information disponible parmi les suivantes : auteur, titre, version, module, fragment de code (par exemple un algorithme spécifique dans un programme), année de parution, licence d'utilisation, URL d'entrepôt. Voici un exemple formatté selon le style Chicago Manual, 17e édition : * Julien Barnier et al.. Scatterd3, version 1.0.1 (2021). GPL. https://cran.r-project.org/web/packages/scatterD3/index.html (en note de fin) * Barnier, Julien, Kent Russell, Mike Bostock, Susie Lu, Speros Kokenes, Evan Wang. Scatterd3 (version 1.0.1). GPL. 2021. https://cran.r-project.org/web/packages/scatterD3/index.html (en référence bibliographique) "

I put this here in case we want to align all author guidelines on this point. Maybe we are not yet at this level of detail but perhaps we'd like to anticipate.

[anisa-hawes]

Thank you for opening this Issue, @spapastamkou! I think this is a practical proposal.

From my point of view, it seems to relate to the conversations we had during our most recent Project Team Meeting, about our lessons as 'snapshots' of how particular methods are used at particular moments in time.

Adding software citations, could be part of a movement towards developing sustainability best-practice guidance that encourages authors to make system dependencies/software versions clear in their opening paragraphs.

[drjwbaker]

CFF is also an option here https://citation-file-format.github.io/ (it is well supported in the research software community)

[acrymble]

@spapastamkou is this resolved? What action do we need to be able to close this ticket?

[spapastamkou]

I believe it needs views from the MEs of EN, ES and PT teams to see if they are willing to integrate these recommendations in their guidelines. @hawc2 @rivaquiroga @DanielAlvesLABDH

[hawc2]

Yes, this makes sense to me to add to our guidelines and start doing regularly

[spapastamkou]

I provide below a quick (and imperfect) translation to English of the fragment of text we provide in the FR author guidelines about how to cite software, in case this may somehow be useful.

"To cite software according to the recommendations of Software Heritage, please provide any element of information available between the following: author, title, version, module, code fragment (for example un specific algorithm in a programme), year of release, license of use, repository URL. Below you will find an example following the Chicago Manual, 17th edition citation style:

• Julien Barnier et al.. Scatterd3, version 1.0.1 (2021). GPL. https://cran.r-project.org/web/packages/scatterD3/index.html (note)
• Barnier, Julien, Kent Russell, Mike Bostock, Susie Lu, Speros Kokenes, Evan Wang. Scatterd3 (version 1.0.1). GPL. 2021. https://cran.r-project.org/web/packages/scatterD3/index.html (bibliography entry) "

[spapastamkou]

Thanks @anisa-hawes I'll keep an eye here and remain at disposal if necessary.

[hawc2]

@anisa-hawes should we start doing this with English lessons going forward? I'm fine with using the French guidelines for English lessons. At the very least we could try to do it at the copyediting/publishing stage and perhaps add a standard subsection of the References to focus on software? It's a fair question to start asking authors to think about. Remediating old lessons will take a while no doubt, but it would be good to start doing this for future publications

[anisa-hawes]

Hello @spapastamkou,

I'm sorry to have left this Issue hanging open for so long. I would like to recommend simplifying this a bit:

EN

To cite software according to the recommendations of Software Heritage, please provide available elements of the following information: author, title, version, year of release, license, repository URL. Below you will find an example following the Chicago Manual, 17th edition citation style:

End note:

Julien Barnier et al.. Scatterd3, version 1.0.1 (2021). GPL. https://cran.r-project.org/web/packages/scatterD3/index.html.

Bibliography entry:

Barnier, Julien, Kent Russell, Mike Bostock, Susie Lu, Speros Kokenes, Evan Wang. Scatterd3 (version 1.0.1). GPL. 2021. https://cran.r-project.org/web/packages/scatterD3/index.html.

--

I'm suggesting that we link to a more specific explanation on the Software Heritage website, rather than to their home page. I am also suggesting omitting the (presumably optional) fields module and code fragment. I'm unclear about the meaning of those terms in this context, having never used SWHIDs and with only a little understanding of BibLaTeX.

I'm not sure about the usefulness of the link to this CTAN webpage. It provides multiple examples of different ways to write bibliographic entries in LaTeX but, as I understand it, we only ever recommend use of LaTex syntax for writing mathematical formulae.

Am I right that SWHIDs are specifically used when authors / developers have created their own scripts from scratch, uploaded their code to a public repository, and generated a unique identifier? In these cases, we could provide the SWHID URL in our citation in place of the repository URL and keep everything else as above?

I think this guidance will help our authors (who may have created their own software from scratch and uploaded it to a public repository, or may be using a specific version of publicly available software).

I think it will also help our copyeditors who are checking endnotes and bibliography entries as part of their work (but are not necessarily technical experts). I think the example citation you provide here is very useful, but the links create some more uncertainty and unknowns (for me).

--

Some thoughts for the future:

Going forwards, as we work on defining the PH tutorial as a genre, I think we could perhaps recommend that every lesson starts with an information box that includes:

• the software used in this lesson (specifying author, title, version, year of release, license, repository URL)
• the computing environment(s) this lesson has been written for / tested in

My sense is that being upfront about these basics could help authors, editors, reviewers and future maintainers to understand a lesson's original computing context and dependencies. It could also help learners and educators to approach the set up and installation sections with clear knowledge about what is variable / new / different within their own toolkit / operating system / set up.

[anisa-hawes]

I've drafted some translations:

---

ES:

Para citar software según las recomendaciones de Software Heritage, facilite los elementos disponibles de la siguiente información: autor, título, versión, año de publicación, licencia, URL del repositorio. A continuación encontrará un ejemplo siguiendo el estilo de citación del Manual Chicago 17ª edición

Nota final:

Julien Barnier et al.. Scatterd3, versión 1.0.1 (2021). GPL. https://cran.r-project.org/web/packages/scatterD3/index.html.

Referencia bibliográfica:

Barnier, Julien, Kent Russell, Mike Bostock, Susie Lu, Speros Kokenes, Evan Wang. Scatterd3 (versión 1.0.1). GPL. 2021. https://cran.r-project.org/web/packages/scatterD3/index.html.

--

FR

Pour citer un logiciel selon les recommandations de Software Heritage, veuillez fournir les éléments disponibles des informations suivantes : auteur, titre, version, année de publication, licence, URL du dépôt. Vous trouverez ci-dessous un exemple suivant le style de citation du Chicago Manual, 17th edition :

Note de fin:

Julien Barnier et al.. Scatterd3_, version 1.0.1 (2021). GPL. https://cran.r-project.org/web/packages/scatterD3/index.html.

Référence bibliographique:

Barnier, Julien, Kent Russell, Mike Bostock, Susie Lu, Speros Kokenes, Evan Wang. Scatterd3 (version 1.0.1). GPL. 2021. https://cran.r-project.org/web/packages/scatterD3/index.html.

--

PT

Para citar software de acordo com as recomendações do Software Heritage, forneça os elementos disponíveis das seguintes informações: autor, título, versão, ano de lançamento, licença, URL do repositório. Abaixo encontra-se um exemplo que segue o estilo de citação do Chicago Manual, 17ª edição:

Nota final:

Julien Barnier et al.. Scatterd3, versão 1.0.1 (2021). GPL. https://cran.r-project.org/web/packages/scatterD3/index.html.

Referência bibliográfica:

Barnier, Julien, Kent Russell, Mike Bostock, Susie Lu, Speros Kokenes, Evan Wang. Scatterd3 (versão 1.0.1). GPL. 2021. https://cran.r-project.org/web/packages/scatterD3/index.html.

[DanielAlvesLABDH]

@anisa-hawes you have become an expert in Portuguese translations. It's perfect

[spapastamkou]

@anisa-hawes

• agree for the link to the specific page
• CTAN webpage: from what I remember the link was because the documentation (in the pdf docs) provides the total of the fields available for one to use in the citation if they want - we only include some of them in the FR guidelines (to simplify). But yes, maybe it is a bit confusing and not a terrible loss if removed
• code fragment: also by memory, it was to anticipate a bit for future lessons, as things run fast :-) - not a terrible loss either
• The FR is already online actually, we had included this when we had updated our guidelines. So the paragraph needs only to be updated in case of changes (omitting a field etc) - cc @marie-flesch

[jenniferisasi]

@anisa-hawes you have become an expert in Portuguese translations. It's perfect

Might as well add Spanish to your CV too :) The translation is perfect. Too bad they have the website in Spanish but not that page in particular :/