Publishing your software

Website: https://dicook.github.io/tutorial-publishing-your-software/

This tutorial is for data analysts and statisticians who work regularly write software in their research. It will describe approaches for writing a publication focused on describing the software. This content will primarily focus on R software, but the approaches would be similar to other software written in other languages. There will group activities and individual activities to help you get started with writing an article on your own software.

Presenter: Dianne Cook, a Professor of Statistics at Monash University in Melbourne, Australia, is a global leader in data visualisation. She has delivered over 100 invited talks internationally and published extensively on various aspects of data visualisation. Dr. Cook is a Fellow of the American Statistical Association, an elected member of the International Statistical Institute, past editor of the Journal of Computational and Graphical Statistics, and the R Journal. She has served as a Board Member of the R Foundation and is currently the co-chair of the Statistical Computing and Visualisation Section of the Statistical Society of Australia.

Presenter: Fonti Kar, a postdoctoral research fellow at The Australian National University and has a background in evolutionary biology, quantitative biology and open-source tool building. She is interested in the sources of biological variability in plant and animal breeding where she leverages mixed modelling techniques to solve agricultural problems. Fonti is currently working on the Analytics for Australian Grains Industry project and is an advocate for openness, in science and in code. She has developed numerous software to support ecological research and maintains the R package ‘austraits’. Fonti is passionate about data science education and empowering others with collaborative coding and package building skills through her committee role on the Statistical Computing and Visualisation Section of the Statistical Society of Australia.

Background: You should have a basic understanding of R, be familiar with Advanced R. Ideally, you have packaged code and made it available on a public archive such as CRAN. This would be a good tutorial for research students to join.

Structure of tutorial

Session 1: Where, why, how

• Setting the scene: Why publish software as an article?
  • Value of software papers in academic careers (citations, recognition, tenure/promotion)
  • Benefits for the community (visibility, credibility, discoverability).
  • Why is a paper better than supplementary material for a regular paper?
  • Common outlets for publishing software:
    • Journal of Statistical Software
    • the R Journal
    • Journal of Open Source Software
    • Methods of Ecology and Evolution
    • Genome Biology
    • Similarities and differences and metrics
    • Review criteria
• Writing the article
  • Problem statement and motivation: why did you write the software? What is special and why others should use it? Why existing tools don’t do the job? Putting your work in the context of existing software
  • Key features of the software
  • Design/implementation details
  • Overview of workflow
  • Examples/use cases/applications/speed comparisons/benchmarking
  • Handling big data, or private data.
  • Handling slow computation/reproducibility.
  • Tips for figures.
  • Reproducibility of your article.
  • Writing a cover letter.

Session 2: Prepare to write your article

• Small group activity: Review some examples of articles of published software
  • Structure
  • Motivation
  • Functionality
  • Usefulness in getting started
• Preparing Your Software for Publication
  • Open source practices
    • Version control, zenodo/DOI, GitHub releases
  • Minimum standards: clear documentation, license, installation instructions.
  • Writing a good README
  • Tests and reproducibility: automated testing, example datasets, vignettes/tutorials.
  • The submission process (journal-specific requirements)
  • Responding to reviewer comments—common issues (docs not clear, lack of tests).
• Hands-on activity:
  • Draft a short abstract for your own software.
  • Sketch an outline for an article on your own software.
  • Identify a target journal.

Copyright: Dianne Cook and Fonti Kar, 2025

These materials are licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.