<!-- .slide: data-state="title blue_overlay yellow_flag yellow_strip purple_half_circle_bottom purple_blob right_e_top" -->
# Software Management Plans
===
<!-- .slide: data-state="standard" -->
## Research reproducibility
<img src="media/maintenance.png" width="40%" title="Software Needs Maintenance">
<small>Image by <a href="https://github.com/c-martinez">Carlos Martinez-Ortiz</a></small>
What role does research software play in promoting reproducibility?
Note:
Reproducibility of research allows validation of its findings, and is therefore vital in building a solid foundation for scientific progress.
We can only truly build upon existing research if we can reproduce its results.
When software has been used in research, this has enormous potential to facilitate the research reproducibility.
However, it also comes with its own particular challenges: software reproducibility is not always straightforward.
===
<!-- .slide: data-state="standard" -->
## Software reusability
- Reproducibility relies on re-using research software.
- Users need to **find**, **access**, and **use** the software.
- Reproduction may just be a first step towards diversifying a study.
- Users need to **understand** the software.
Software reusability encompasses both **reproducing** existing results obtained with RS, as well as **building upon** existing RS to use it in new or different ways.
Software Management Plans help developers ensuring that their research software is reusable.
Note:
An additional feature of software, is that it may be a product on its own, and can be reused by others.
This is a great opportunity to build on our collective knowledge and tools, and to avoid reinventing the wheel.
Ensuring that the software is findable, accessible, usable, and understandable is key to both reproducibility and reusability.
Software needs to be understood both from a:
- functional perspective: what steps does the software take to get to the results
- developmental perspective: how are these steps put into code
===
<!-- .slide: data-state="standard" -->
## Overview
<!-- TODO change to reflect actual structure -->
- Software Management Plan: what and why?
- Aspects of software management
- Different needs for different software
- SMP guided questionnaire
Note:
This presentation will introduce you to the concept of software management plans, as a first step towards better software stewardship and sustainability.
We will look at different aspects of good software managements, as well as different needs for different types of software.
Finally, we will take a look at how to create a software management plan.
About the "Different needs for different software": an SMP can sometimes be very short. To not frighten people that they have to create an extensive big SMP for each case; the SMP is just meant as a tool to help you think about software management.
===
<!-- .slide: data-state="standard" -->
### Software Management Plan (SMP)
- Building on the success of Data Management Plans (DMPs)
- A document detailing how research software will be managed
- What does it do?
- Who is it for?
- What resources does it need?
- Who is responsible?
- How long will it be available?
- Can be part of a project proposal or generated in the early phases
> An SMP is a "living document", to be updated as plans change!
Note:
Software management plans (SMPs) are inspired by the earlier adopted data management plans.
In these documents, often created at or before the start of a project, plans and explicit decisions are made about various aspects around the management of these digital objects.
They are increasingly required by funders and institutions.
In an SMP it is explicitly stated what the software aims to do, who its target audience is, and what resources it is expected to need.
It also addresses the intended lifespan, and allocates responsibility: who makes releases? Who maintains the software at the end of the project, and if so for how long?
===
<!-- .slide: data-state="standard" -->
## An SMP helps ...
<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 10px; text-align: center;">
<div>
<img src="media/benefits/purpose.png" style="height: 100px;">
<sub>... thinking about<br>purpose & necessity</sub>
</div>
<div>
<img src="media/benefits/resources.png" style="height: 100px;">
<sub>... planning<br>resource management</sub>
</div>
<div>
<img src="media/benefits/problems_later.png" style="height: 100px;">
<sub>... avoiding<br>problems later</sub>
</div>
</div>
<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 10px; text-align: center; margin-top: 60px; margin-bottom: 60px;">
<div>
<img src="media/benefits/structure.png" style="height: 100px;">
<sub>... structuring<br>development</sub>
</div>
<div>
<img src="./media/benefits/explicit.png" style="height: 100px;">
<sub>... making technical<br>choices explicit</sub>
</div>
<div>
<img src="media/benefits/alive.png" style="height: 100px;">
<sub>... keeping research<br>software alive</sub>
</div>
</div>
<small>Images generated by OpenAI's DALL·E 3 model via ChatGPT v2 and subsequently adapted by <a href="https://github.com/DaniBodor">Dani Bodor</a>.</small>
Note:
With an SMP, you make explicit plans and decisions in an early stage.
The SMP provides the team with structured, relevant questions early on, with the aim to maximize the accessibility, reusability, and impact of the software in question.
This supports good software management practices, and it makes sure they are known to the researchers involved.
More specifically, in an SMP you:
- Make explicit technical choices. For example, what programming language will be used? What operating system will be supported?
- Plan for necessary resources; be they financial, human, infrastructure or other.
- Assess whether new software is really needed; explore whether existing software can be reused, and to what extent;
These are issues that arise during software development anyway, but all too often are not explicitly dealt with.
By tackling them early, a conscious decision can be made rather than needing to deal with consequences of implicit choices.
Resource planning moreover is vital for the sustainability of the software.
Finally, the SMP will allow later verification of plans in a publicly funded project.
==
<!-- .slide: data-state="standard" -->
## An SMP is not ...
an additional bureaucratic hoop for researchers to jump through.
Make sure you represent it as a tool allowing researchers to get the most out of their effort.
Note:
It is a common trap to present such documents to researchers and "force" them
to fill them in without too much context. This is then often perceived as a
bureaucratic burden that is not done with a lot of care or attention.
Instead, we recommend presenting SMPs as an agent allowing researchers to
minimize their efforts, by making considerations early in the process and
working towards their goals, rather than having to make the call in the moment,
when there may be other priorities/deadlines (publication, grant application,
...)
===
<!-- .slide: data-state="standard" -->
## Not all software is equal
Note:
It is important to realize when making an SMP, that research software comes in many shapes and sizes.
An ad-hoc R script written by a PhD student to analyse data from a specific machine, is research software.
It can also be a multinational collaboration to develop a tool that is used by thousands of researchers worldwide.
Different software has different needs, but there are common principles in managing them and ensuring their sustainability.
The diversity of research software does mean that not all requirements apply to every type of software.
To address this, we can subset the core requirements to create different SMP templates tailored to software with different management needs.
The SMP Guide distinguishes software with low, medium, and high management needs.
===
<!-- .slide: data-state="standard" -->
<center>
<img src="media/smpguide.png" width="50%" />
[doi:10.5281/zenodo.7038280](https://doi.org/10.5281/zenodo.7038280)
</center>
Note:
To get started on creating a Software Management Plan, this practical guide has been created by NWO and the Netherlands eScience Center.
Its first version was released in August of 2022, but it has since been, and will continue to be, updated.
All past versions and the latest release are available on Zenodo via this DOI.
===
<!-- .slide: data-state="standard" -->
## SMP Guided Questionnaire
[smp.research.software](https://smp.research.software)
<dl>
<dt>1. Determine the Scope</dt>
<dd>4 scope questions</dd>
<dt>2. Fill in SMP</dt>
<dd>7-15 content questions</dd>
<dt>3. Download SMP</dt>
<dd>
- Word document,
- Machine-readable file, or
- Copier template input
</dd>
</dl>
Note:
The questionnaire extends the [Practical Guide to Software Management Plans](https://doi.org/10.5281/zenodo.7038280) and makes it easy to use.
**Scope**
Simple projects will get less questions, while complex one require more information.
**Machine readable SMP**
For automated analysis
**Copier template input**
When setting up a new Python project using the NLeSC Copier Template, this file can be passed using `--data-file=copier_template_answers.yml` to already fill in some questions.
==
<!-- .slide: data-state="standard" -->
### Determine the Scope
1. Is or will the software be publicly available?
1. Will the software be reused, or is it only used once?
1. Are there or will there be any other users apart from yourself?
1. Is there or will there be a community around the software?
==
<!-- .slide: data-state="standard" -->
### Fill in SMP
<div style="float: left; width: 49%;">
#### Mandatory
- Name & Purpose
- Authors
- Ownership
- Research Context
- Versioning
- Risks
- Data Management Plan
</div>
<div style="float: left; width: 49%;">
#### Optional
- License
- Documentation
- Citation
- Maintenance
- Sustainability
- Support
- Software Quality Checklist
- Packaging
</div>
Note:
The optional questions depend on the previously determined scope.
===
<!-- .slide: data-state="standard" -->
## Which SMP to Use?
#### SMP Questionnaires or Templates...
- Should be provided by the institution
- Include guidance:
- Instructions on how to fill it out
- Resources for information and support
- Institution-specific regulations
- Institution-specific resources available
- Who to contact for clarification/further information
- Include an assessment rubric (e.g. with (un)acceptable answers)
Note:
The Software Management Plan template is a duty of the institution.
A good SMP includes guidance on how to fill it out, including institution-specific regulations and resources.
An assessment rubric should accompany the template, indicating per question or focus what conditions need to be met, and which answers are (un)acceptable.
===
<!-- .slide: data-state="standard" -->
## Take home messages
- Software is found in all stages of the research cycle
- Research software comes in many shapes and sizes
- Software stewardship starts with a good plan
- Good software management leads to better science
- Institutes should provide one or more<br>SMP templates or guidelines, e.g.
- Use [smp.research.software](https://smp.research.software), or
- Fork [github.com/SS-NES/docassemble-SMPDecisionTree](https://github.com/SS-NES/docassemble-SMPDecisionTree)
Note:
Software is found in all stages of the research cycle, and is used for many different purposes.
It comes in many shapes and sizes, and has different needs.
Software stewardship starts with a good plan, and is an important scientific step: good software management leads to better science.
===
<!-- .slide: data-state="keepintouch" -->
[www.esciencecenter.nl](https://www.esciencecenter.nl)
info@esciencecenter.nl
020 - 460 47 70
