From b9dacc8240ab5500ee0508b7b0eb9e30dbb70360 Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Tue, 15 Oct 2024 16:18:15 +0100 Subject: [PATCH 1/3] Add a section on software papers --- episodes/introduction.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/episodes/introduction.md b/episodes/introduction.md index 34817fe..dd27297 100644 --- a/episodes/introduction.md +++ b/episodes/introduction.md @@ -70,6 +70,26 @@ This might include design notes, diagrams, or the various kinds of software docu **Keep in touch** with other developers and users of the research code and make a note of their feedback. Common questions and problems are a sign that there are issues that must be covered more clearly and in greater depth in the software documentation. **Incorporate this feedback** into the software documentation using the whichever method is most appropriate, following the guidance in this module. +## Research software papers + +You may decide to publish a description of your **software as a paper** in an academic journal. This is a kind of [methods paper](https://book.the-turing-way.org/communication/dif-articles/methods.html), which provides more detail on your research process than is possible in your main paper. + +A research software paper should provide a **concise introduction** to your code and explain why it was written. It may contain a detailed description of the technical design and how algorithms are implemente, providing transparency to other researchers and enabling better replicability of your results. + +For more information about writing these papers, which is beyond the scope of this course, please read [Ten simple rules for writing a paper about scientific software](https://doi.org/10.1371/journal.pcbi.1008390) by Joseph Romano. + +:::: Software journals + +An increasing number of journals allow and encourage the publication of research software and open data. Some journals focus on a specific field, while others primarily publish research software of any kind. Some relevant journals include: + +- [*The Journal of Open Source Software*](https://joss.theoj.org/) is a peer-reviewed publications that provides academic citations for research code; +- [Nature](https://www.nature.com/) has a category of [Toolbox articles](https://www.nature.com/nature/articles?type=toolbox) that cover the technical side of research; +- [Journal of Open Research Software](https://openresearchsoftware.metajnl.com/) is a peer-reviewed repository run by the [Software Sustainability Institute](https://www.software.ac.uk/). + +For more information, please read [In which journals should I publish my software?](https://www.software.ac.uk/top-tip/which-journals-should-i-publish-my-software) by Neil Chue Hong, the Director of the [Software Sustainability Institute](https://www.software.ac.uk/). + +:::: + ## Examples Here are some examples of some code to perform some geometry. The first example could be improved in terms of its documentation and readability, while the second one is much clearer. From 2c3060d14e6ff1d672b054ad1f1171d8b1bc3a3c Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Tue, 15 Oct 2024 16:23:33 +0100 Subject: [PATCH 2/3] spoiler block --- episodes/introduction.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/episodes/introduction.md b/episodes/introduction.md index dd27297..197076d 100644 --- a/episodes/introduction.md +++ b/episodes/introduction.md @@ -78,7 +78,9 @@ A research software paper should provide a **concise introduction** to your code For more information about writing these papers, which is beyond the scope of this course, please read [Ten simple rules for writing a paper about scientific software](https://doi.org/10.1371/journal.pcbi.1008390) by Joseph Romano. -:::: Software journals +:::: spoilers + +### Software journals An increasing number of journals allow and encourage the publication of research software and open data. Some journals focus on a specific field, while others primarily publish research software of any kind. Some relevant journals include: From 0371945d6aa774d024e076eb7c98997ed2de7c97 Mon Sep 17 00:00:00 2001 From: Joe Heffer Date: Tue, 15 Oct 2024 16:24:37 +0100 Subject: [PATCH 3/3] - --- episodes/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/introduction.md b/episodes/introduction.md index 197076d..5d67437 100644 --- a/episodes/introduction.md +++ b/episodes/introduction.md @@ -74,7 +74,7 @@ This might include design notes, diagrams, or the various kinds of software docu You may decide to publish a description of your **software as a paper** in an academic journal. This is a kind of [methods paper](https://book.the-turing-way.org/communication/dif-articles/methods.html), which provides more detail on your research process than is possible in your main paper. -A research software paper should provide a **concise introduction** to your code and explain why it was written. It may contain a detailed description of the technical design and how algorithms are implemente, providing transparency to other researchers and enabling better replicability of your results. +A research software paper should provide a **concise introduction** to your code and explain how and why it was written. It may contain a detailed description of the technical design and how algorithms are implemente, providing transparency to other researchers and enabling better replicability of your results. For more information about writing these papers, which is beyond the scope of this course, please read [Ten simple rules for writing a paper about scientific software](https://doi.org/10.1371/journal.pcbi.1008390) by Joseph Romano.