Software Papers#

What are Software Papers?#

In comparison to more traditional publications, which usually aim to share some new result, a software paper (sometimes known as a software metapaper) aims to share a new piece of software with the research community. In this sense, software papers are close to method papers traditionally published in experimental sciences. Software papers tend to be shorter than traditional articles, typically ranging between 2 and 10 pages, and focus on describing the software, its use and its relationship to other pieces of software in the community. This helps fill the niche between methods sections in traditional publications and papers on algorithms or techniques.

Why write a Software Paper?#

Software papers are much shorter than traditional publications, allowing more time to be spent on the software while still providing an avenue for publication. By specifically publishing in a software-focused journal, you are exposing your software to an audience which is already engaged with research software. You are also adding your software to a curated index of high-quality, peer-reviewed code, increasing the likelihood that your code will be found and used by another researcher. Through the peer-review process, not only is the paper itself evaluated, but the associated code can sometimes be reviewed. Just as in traditional publishing, this process is intended to provide constructive feedback, helping to improve the quality of the software and surrounding systems.

In short, you should write software papers to:

  • advertise your code to an interested audience

  • increase the visibility of your code and community

  • improve your software through peer-review

How do you write a Software Paper?#

In a broad sense, software papers tend to focus on answering the questions:

  • What does the software do?

  • How do we know the software is correct?

  • Why is the software unique?

  • How can I learn how to use the software?

The specific sections included in a software paper vary with journal but generally a paper should contain:

  • A description of the problem the software solves

  • A comparison to similar software in the space

  • An overview of methods and techniques implemented by the software

  • A description of the implementation and architecture

  • Details of test cases which validate the software

  • Links to further details of the implementation

  • Links to documentation on installation and use of the software

Both the Journal of Open Research Software and the Journal of Open Source Software provide publicly accessible review checklists, which provide concrete details about what to include in a software paper:

There are also a number of other journals that publish software papers- the Software Sustainability Institute maintain a list of these.

How do you review a Software Paper?#

Some journals (such as the Journal of Open Research Software) adopt the philosophy that the review process only applies to the paper itself, not the software, although basic standards in the software are still enforced, for example, that the software installs and operates as described.

While many journals encourage publishing software that has been used in published research, in order to strengthen the case for publication, it is not typically a strict requirement.

In JOSS specifically, the review process is entirely open and non-anonymous. You can find current and past reviews on their review tracker.