From 401ca55b4b887c5cd5821b08f33d9c3375228a44 Mon Sep 17 00:00:00 2001 From: Denis Yuen Date: Thu, 5 Dec 2024 17:47:11 -0500 Subject: [PATCH] Feature/doi intro (#295) * test render * finish off blurb --- docs/end-user-topics/dois.rst | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/end-user-topics/dois.rst b/docs/end-user-topics/dois.rst index c5d8c557..951eadef 100644 --- a/docs/end-user-topics/dois.rst +++ b/docs/end-user-topics/dois.rst @@ -3,10 +3,38 @@ Digital Object Identifiers Introduction ------------ + +Why would you need a DOI? +~~~~~~~~~~~~~~~~~~~~~~~~~ + A Digital Object Identifier (DOI) is a permanent identifier that can be used in publications to identify the exact -version of a workflow or tool (entry). DOIs are commonly referenced from academic papers. +version of a workflow or tool (entry). A DOI can be used by both humans and machines to resolve a reference +to a piece of information or data in a persistent way. DOIs are commonly referenced from academic papers. + See the `DOI Foundation `__ for more details. +Why would you need a DOI for software? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When others use your software, they should cite your software and what version of your software was used, especially in the methods section. +In addition, in the context of reproducible science, it can be critically important for readers to understand which version of your software was used +since different versions of software can have different performance or can be compatible with different platforms. +Nothing can be more frustrating than not knowing what version of a piece of software should be used in addition to not knowing in what environment it should be used. + +Citing the version of software used is not intended to supplant a traditional scholarly publication, but is intended to supplement it. +This can help future researchers to run your software both in new contexts or in larger contexts. In particular, the software DOI approaches that we recommend point to +an archive (sometimes frozen for more certainty) of the source code for the version of the workflow in question. +This archive can include all or some of the other pieces of information that we recommend such as a Dockerfile(s) to describe the creation of the environment +for the source code, licensing information, test parameter files, and more. + +See the `Software citation principles `__, +the link rot and redundancy discussions of `Ten simple rules for writing a paper about scientific software `__, +and `How Not to Cite Software (and how to be cited) `__, +for more details. + +Dockstore Support for DOIs +-------------------------- + Creating and assigning DOIs is commonly known as "minting". Many repositories mint DOIs. Dockstore currently only supports `Zenodo `__ DOIs. Dockstore uses Zenodo to mint DOIs, and it can also recognize DOIs generated by Zenodo outside of Dockstore. @@ -14,9 +42,6 @@ Zenodo supports `DOI versioning