Writing and using a software management plan
It is easy to concentrate on the short-term issues when developing scientific software. Deadlines for publications, collaboration with others and the demands of a daily routine all conspire to prevent proper planning. A software management plan can help to formalise a set of structures and goals that ensure your software is accessible and reusable in the short, medium and long term. This guide takes you through the questions you should consider when developing a software management plan.
This page provides guidance on what you should consider when writing a software management plan. This advice will continue to be refined as we get more feedback from different research funders on their requirements and priorities. We also aim to collect examples of good software management plans from different types of project.
Why develop a software management plan?
There are several benefits to having a plan to manage and share your software:
- Better understanding of roles and responsibilities in the project
- Better continuity if members of your team change
- Better estimation and planning of effort and resources required
- Reduction of reputational and organisational risk
- Facilitates engagement with your user and developer communities
- Makes it easier for others to make use of and reuse your software
- Others will find it easier to cite your software
- Software related to publications can be preserved/archived for future validation and repeatability/reproducibility of the research
- Your work is more visible and has a potentially greater impact
- Higher likelihood that your software will meet the needs of the people who use it
What do research funders want?
At present software management plans are relatively new for research software proposals, though many of the elements discussed below would be expected in standard proposals.
The EPSRC Software for the Future call explicitly requires software management plans as part of the Pathways to Impact. NSF SI2 funding requires software to be addressed as part of the mandatory data management plan.
Developing your plan
As the software management plan is principally for your project's own use, the most important thing is to develop the plan in conjunction with your project team and partners, as you will all be responsible for following the plan.
In particular, it is important to get an idea of the roles and responsibilities. All partners should sign up and commit to the plan.
Basics of a software management plan
A software management plan can take many forms, depending on the requirements from your funder and the size of your project. It's important to tailor a plan format so that you will use it. A minimal software management plan might be a single paragraph, whereas a detailed plan might run to several pages. A software management plan should focus on the software outputs you expect to produce and how they will be managed through the development and delivery stages.
A software management plan should minimally include:
- information on what software outputs (including documentation and other related material) are expected to be produced [Note: it's not as important to define the functionality in detail, as this may change in a research software project];
- who is responsible for releasing the software [Note: this is often the PI, project manager or lead developer but may a specific role];
- the revision control process to be used [Note: it is important to choose a revision control / configuration management system that all members of the team will use];
- what license will be used for each output [Note: this might require input from your funder or institution].
A software management plan could also:
- identify the software development model to be used;
- identify the external software that will be brought into the project, and the associated licences;
- what method will be used to accept each output (e.g. a specific user will review it);
- dependencies between outputs and with external dependencies;
- major risks that might impact on the delivery of the outputs.
A software management plan might also identify who is responsible for delivery of each output, and the expected delivery milestones or stages, though this is often part of the Workplan for a project.
The following subsections suggest questions you should ask whilst developing your plan.
Software assets used and produced
- What software will be used by your project?
- What software will be produced by your project?
- What are the dependencies / licenses for third party code, models, tools and libraries used?
- What would be the process for keeping an up to date list of software assets and dependencies?
Intellectual Property and Governance
- Have you chosen an appropriate licence for software developed by your project?
- Is your license clearly stated and acceptable to all partners?
- Do you have a governance model for your project or product?
- What are the licenses for third party code, models, tools and libraries used?
- Are there are issues with the compatibility of licenses for third party code, tools or libraries?
- Are there any issues that you are aware of to do with patents, copyright and other IP restrictions?
Access, sharing and reuse
- Have you identified suitable project infrastructure early, particularly a code repository (either in-house or public)?
- Will your project repository be public or private? Do you have a requirement for private storage?
- What is required to be shared between partners / more widely?
- How you will manage releases (how often, how delivered, how will you decide when to release)?
- How will you ensure you deliver "what's needed" (e.g. acceptance criteria)?
- How will you ensure you deliver "correct" code (e.g. tests, frameworks, checklists, quality control)?
- How you will deliver readable code that can be understood by others (e.g. documentation, coding standards, code reviews, pair programming)?
- How will you make it easier for new team members to run and develop the software?
- How will you make it easy to write and run new tests?
- How will you make it easy to reference and cite the software produced by your project?
- Where will you deposit software for long-term preservation/archival?
- Does your institutional repository allow deposit of software?
- Does your chosen repository have a clear preservation policy?
- Is your chosen repository part of a distributed preservation collection?
- How will you tracking data formats used (related to your data management plan)?
- How will you record specific and implicit dependencies (e.g. browsers, operating systems, SDKs) required by your software?
- Do you have a need to record and track versions of service interfaces and any use of open or proprietary standards that may change/become superceded by others?
- Does your software require access to any public web services / infrastructure / databases that may change or disappear?
Resourcing and responsibility
- What software development model will you aim to use?
- How you will support your software (how much effort is available, what level of service will you offer, how will you interact)? Will this change over time?
- What effort is available to support the software (funded on your project, unfunded volunteers, temporary, students)?
- Whose responsibility is it for different roles (e.g. project manager, build manager, technical authority, change board, support requests)?
- How you will track who does and has done what (e.g. TODOs, issues, bugs and queries)?
- How do you ensure adequate knowledge exchange within the team to ensure that knowledge is not lost when people leave (e.g. documentation, pair programming, reviews)?
- How often will you review and revise the software management plan?
- How does your software management plan relate to any data management plan?
W. Anderson, E. Morris, D. Smith, and M. Ward, "COTS and Reusable Software Management Planning: A Template for Life-Cycle Management," Software Engineering Institute, Carnegie Mellon University, Pittsburgh, Pennsylvania, Technical Report CMU/SEI-2007-TR-011, 2007.
Thanks to input given by Rob Baxter, Steve Crouch, Mike Jackson, Tim Parkinson. Thanks also to Kevin Ashley and all at the DCC for their work on Data Management Plan guidance. We particularly acknowledge the structure of their guides which have been used as a basis for this guide.