Posted by m.jackson on 11 December 2018 - 4:41pm Image by Mark McNestry. 

By Mike Jackson, Research Software Engineer.

When developing research software, we need to know what we are going to write, who it is for (even if this is just us), how we will get it to them, how it will help them, and how we will evaluate whether it has helped them. A Software Management Plan (SMP) can help us think about these and decide upon the processes we will use when developing our software. To help write SMPs, we have now published version 1.0 of our Checklist for a Software Management Plan.

Why write a Software Management Plan?

Research software can take many guises. It can be a 50 line bash shell script for manipulating and filtering files, a collection of 100 line R scripts for running a bioinformatics analysis, 10,000 lines of Java for medical image analysis or 100,000 lines of Fortran for computational fluid dynamics. It may be written in scripting languages such as Unix shell, Python, R or MATLAB or in "traditional" programming languages such as C, C++, Fortran or Java. But, whatever guise it takes, research software is an integral part of the modern research ecosystem.

When developing research software, it is easy to focus only on goals and activities such as collaborating with other researchers, writing papers, attending conferences and applying for funding. Together, the demands of daily research practice can all conspire to prevent proper planning for the development of research software.

A software management plan (SMP) can help us to define a set of structures and goals to understand our research software including what we are going to develop; who the software is for (even if it is just for ourselves); how we will deliver our software to its intended users; how it will help them; and how we will assess whether it has helped them, and contributed to research, in the ways that we intended. An SMP also helps us to understand how we can support those who wish to, or do, use our research software; how our software relates to other artefacts in our research ecosystem; and how we will ensure that our software remains available beyond the lifetime of our current project.

Though an SMP can be of most benefit when starting a project to develop research software, there are benefits to adopting one on a project that is already underway. An SMP provides a way to draw together and summarise research software-related aspects that have already been decided and doing so can reveal additional aspects or options that weren't considered, or weren't applicable, when the project began.

Origins

Our checklist originates from 2012 when our director, Neil Chue Hong, wrote a guide on Writing and using a software management plan. This guide summarised the key elements that an SMP should include. The guide was influenced by the work of the Digital Curation Centre (DCC) on data management plans, in particular the DCC's Checklist for a Data Management Plan.

Prototype software management plan service

Both our advisory board and participants at our Collaborations Workshop 2012 suggested that we complement our guide with an online service. The service could help researchers understand issues around research software, appreciate why SMPs are important and assist in their authoring. Rather than create a service from scratch, we decided to practice what we preach and see if we could reuse an existing research output, DMPonline. DMPonline is DCC's data management plan service which helps researchers write data management plans. In 2015, we customised DMPonline into a prototype software management plan service. This service, hosted by the Institute, offered advice based on our guide, and was described in our blog post Software Management Plan Service prototype live.

Checklist for a software management plan and DMPonline

In the year following the deployment of our prototype, we drew together advice and guidance to help researchers write software management plans and in 2016 published our Checklist for a Software Management Plan (v0.1). The checklist was closely aligned to the structure of the DCC's Checklist for a Data Management Plan, consisting of a set of sections relating to specific aspects of research software, with questions pertinent to each section, and complemented by additional questions to consider, guidance and links to third-party resources. 

DCC granted us permission to create a template corresponding to our checklist within DMPonline, removing the requirement for us to host our own service. Our checklist, and its hosting within DMPonline, was described in our blog post Write Software Management Plans with DMPonline.

Less is more

Come spring 2018 and there seemed to be very little use of the SMP features within DMPonline. Also, over the years I'd become increasingly unhappy with the checklist both due to its length (8 sections, 41 questions, 25 pages when printed!) and because it degenerates into a "how to plan and run a software project", asking for specific details on myriad aspects around revision control, testing, documentation, dependencies etc. The latter are far more effectively covered in any number of software development books and resources. Other researchers had also remarked on its intimidating heft!

Discussions both within and outwith the Institute showed an interest in reducing the size of the checklist, scaling back to a small set of key questions any researcher should be able to answer: What software will you develop? Who are the intended users of your software? How will you make your software available to your users? How will your software contribute to research? and, How will you measure your software's contribution to research? Our Jisc-funded work on Software Deposit Guidance for Researchers earlier this year motivated three others: How will you support those who use your software? How will your software relate to other research objects? and, Where will you deposit your software to guarantee its long-term availability?

Checklist for a Software Management Plan v1.0

These changes have now been applied and our new, leaner Checklist for a Software Management Plan (v1.0) (doi: 10.5281/zenodo.2159713) is now available from Zenodo. The checklist is complemented by templates in Markdown, Microsoft Word, and OpenOffice/Libre office formats, which researchers can customise and complete.

We hope that our new checklist is of use to research software developers and principal investigators. We welcome any suggestions as to how it can be improved or how it has been used in practice. Please feel free to contact us about any aspect of software management plans.