Merge pull request #27 from esciencecenter-digital-skills/smp_migration

Covert SMP to new format
esciencecenter-digital-skills · Apr 8, 2024 · 4362bfd · 4362bfd
2 parents 5b72459 + 6878aff
commit 4362bfd
Show file tree

Hide file tree

Showing 6 changed files with 148 additions and 149 deletions.
diff --git a/modules/smp.md b/modules/smp.md
@@ -7,142 +7,5 @@ author: eScience Center
 thumbnail: "nlesc-dummy.png"
 visibility: visible
 ---
-:::Chapter{headline="Introduction: slides" presentation="slides-smp.md"}
 
-:::
-
-:::Chapter{headline="SMPs" widemd=1}
-
-## Software Management Plans (10 minutes)
-
-Research software plays a crucial role in academic research and has become a key output of many research projects. A software management plan helps to implement best practices during software development and ensures that software is accessible and reusable in the short and longer term. It also contributes to the reproducibility of results and stimulates collaborative work on open-source software for research.
-
-In practice, a software management plan helps:
-
-- Assess whether developing new software is necessary
-- Plan to make the research software reusable and sustainable
-- Plan for necessary resources
-- Allow for verification of work that went into implementation
-
-In the Practical Guide to Software Management plans, this is described in more detail:
-
-[A practical guide to software management plans](https://zenodo.org/record/7589725)
-
-After reading this guide, you should:
-
-- Be aware of different types of research software
-- Understand different demands placed on these types of software
-- Know about various aspects of software management
-- Be able to explain the importance of a software management plan for software sustainability.
-
-:::
-
-:::Chapter{headline="Exercise: SMPs in practice" widemd=1}
-
-*In a live seting, this exercise is done in groups.
-Each group will be assigned a software project.
-The group will then create an SMP for this project.*
-
-## Step 1: Choose a software project
-
-Choose a software project for this exercise, preferably one you are familiar with.
-
-If you don't have a project in mind, you can use one of the following:
-- [Xenon](https://research-software-directory.org/software/xenon)
-- [ESMValTool](https://research-software-directory.org/software/esmvaltool)
-- [RS-DAT](https://research-software-directory.org/projects/rs-dat)
-- [Haddock](https://research-software-directory.org/software/haddock3)
-- [worcs](https://cjvanlissa.github.io/worcs/index.html)
-
-Find the Practical Guide at [tinyurl.com/SMP-guide](https://doi.org/10.5281/zenodo.7589725).
-
-## Step 2: Assess the management level needed
-
-- Look at the software repository or page in the Research Software Directory
-- Assess what level of management the software needs: low, medium, or high.
-
-For this, use the following considerations (section 5 in [the guide](https://doi.org/10.5281/zenodo.7589725)):
-
-1. **Purpose**. What is the current reason or expected end-use for developing the software?
-2. **Reliability**. The effect of software failure and/or non-maintenance on:
-    - Risk of harm to self or others. This includes injury, privacy violation, bias, and inappropriate content.
-    - Reputation. For example to self, institution or other.
-    - Research, either your own or of others. This effect could be due to an obvious software failure ("crash") or a hidden one, for example, returning inconsistent numerical results on different operating systems.
-3. **Maintenance**. The long-term effort needed to maintain the software as long as it might be used as a standalone tool or dependency. This includes maintenance functions that can extend beyond the lifespan of the original development project and includes fixing bugs, dependency management, operating system compatibility, and security issues.
-
-This may not be a clear-cut decision, but that is fine.
-The goal is to get a sense of the level of management needed.
-Discuss with your group and come to a consensus.
-
-## Step 3: Fill in the SMP template
-
-From the assessment made in Step 1, get the requirements that match the level of management needed.
-
-Copy a template, and fill it in for your software project.
-
-:::
-
-
-:::Chapter{headline="Exercise: SMP v FAIR" widemd=1}
-
-## SMP vs FAIR
-
-### Why do we care?
-
-When thinking of the importance of good software stewardship, management, and development practice, many reasons and motivations come to mind.
-You may think of:
-
-- Accuracy of results
-- Reproducibility of results
-- Reusability of software
-- User friendliness of software
-- Software quality
-- Recognition and rewards for software developers
-- Scholarly archive
-- Software sustainability
-
-What are the reasons and motivations that come to mind for you?
-
-### Mapping motivations
-
-(**NB:** If you are not yet familiar with the FAIR principles for research software, [take a look at the chapter on FAIR software](/fairsoftware) before doing the following exercise.)
-
-The motivations we listed above were important considerations for the development of Software Management Plans as well as the FAIR principles for research software.
-They do not match completely, however.
-Each has its own focus and emphasis.
-
-In the following exercise, we will map the motivations we listed above to the ultimate goals of SMPs and the FAIR principles.
-
-Draw a Venn diagram with two circles: SMP and FAIR:
-
-<img src="venn_fairsmp.png" width="400">
-
-Map the motivations listed above to the Venn diagram.
-
-- Which motivations are covered by SMPs, which by FAIR, and which by both?
-- Do you find any motivations that are not covered by either?
-- What does this tell you about the relationship between SMPs and FAIR?
-
-:::
-
-
-:::Chapter{headline="Resources" widemd=1}
-
-## Overview of practical guides
-
-There are various practical guides online to the different aspects of software management.
-
-Here is an (incomplete) list:
-
-- [Version control](https://the-turing-way.netlify.app/reproducible-research/vcs.html)
-- [Testing](https://the-turing-way.netlify.app/reproducible-research/testing/testing-guidance.html)
-- [Packaging](https://the-turing-way.netlify.app/reproducible-research/renv/renv-package.html)
-- [Documentation](https://guide.esciencecenter.nl/#/best_practices/documentation)
-  - User
-  - Deployment
-  - Developer
-- [Citation](https://the-turing-way.netlify.app/communication/citable/citable-cff.html#cm-citable-cff)
-- [Software licensing](https://the-turing-way.netlify.app/reproducible-research/licensing/licensing-software.html) and [compatibility](https://the-turing-way.netlify.app/reproducible-research/licensing/licensing-compatibility.html)
-
-
-:::
+# Software Management Plans
diff --git a/modules/smp/exercise1.md b/modules/smp/exercise1.md
@@ -0,0 +1,23 @@
+# Exercise 1
+
+## Software Management Plans (10 minutes)
+
+Research software plays a crucial role in academic research and has become a key output of many research projects. A software management plan helps to implement best practices during software development and ensures that software is accessible and reusable in the short and longer term. It also contributes to the reproducibility of results and stimulates collaborative work on open-source software for research.
+
+In practice, a software management plan helps:
+
+- Assess whether developing new software is necessary
+- Plan to make the research software reusable and sustainable
+- Plan for necessary resources
+- Allow for verification of work that went into implementation
+
+In the Practical Guide to Software Management plans, this is described in more detail:
+
+[A practical guide to software management plans](https://zenodo.org/record/7589725)
+
+After reading this guide, you should:
+
+- Be aware of different types of research software
+- Understand different demands placed on these types of software
+- Know about various aspects of software management
+- Be able to explain the importance of a software management plan for software sustainability.
diff --git a/modules/smp/exercise2.md b/modules/smp/exercise2.md
@@ -0,0 +1,42 @@
+# Exercise 2
+
+*In a live setting, this exercise is done in groups.
+Each group will be assigned a software project.
+The group will then create an SMP for this project.*
+
+## Step 1: Choose a software project
+
+Choose a software project for this exercise, preferably one you are familiar with.
+
+If you don't have a project in mind, you can use one of the following:
+- [Xenon](https://research-software-directory.org/software/xenon)
+- [ESMValTool](https://research-software-directory.org/software/esmvaltool)
+- [RS-DAT](https://research-software-directory.org/projects/rs-dat)
+- [Haddock](https://research-software-directory.org/software/haddock3)
+- [worcs](https://cjvanlissa.github.io/worcs/index.html)
+
+Find the Practical Guide at [tinyurl.com/SMP-guide](https://doi.org/10.5281/zenodo.7589725).
+
+## Step 2: Assess the management level needed
+
+- Look at the software repository or page in the Research Software Directory
+- Assess what level of management the software needs: low, medium, or high.
+
+For this, use the following considerations (section 5 in [the guide](https://doi.org/10.5281/zenodo.7589725)):
+
+1. **Purpose**. What is the current reason or expected end-use for developing the software?
+2. **Reliability**. The effect of software failure and/or non-maintenance on:
+    - Risk of harm to self or others. This includes injury, privacy violation, bias, and inappropriate content.
+    - Reputation. For example to self, institution or other.
+    - Research, either your own or of others. This effect could be due to an obvious software failure ("crash") or a hidden one, for example, returning inconsistent numerical results on different operating systems.
+3. **Maintenance**. The long-term effort needed to maintain the software as long as it might be used as a standalone tool or dependency. This includes maintenance functions that can extend beyond the lifespan of the original development project and includes fixing bugs, dependency management, operating system compatibility, and security issues.
+
+This may not be a clear-cut decision, but that is fine.
+The goal is to get a sense of the level of management needed.
+Discuss with your group and come to a consensus.
+
+## Step 3: Fill in the SMP template
+
+From the assessment made in Step 1, get the requirements that match the level of management needed.
+
+Copy a template, and fill it in for your software project.
diff --git a/modules/smp/exercise3.md b/modules/smp/exercise3.md
@@ -0,0 +1,39 @@
+# Exercise 3
+
+## SMP vs FAIR
+
+### Why do we care?
+
+When thinking of the importance of good software stewardship, management, and development practice, many reasons and motivations come to mind.
+You may think of:
+
+- Accuracy of results
+- Reproducibility of results
+- Reusability of software
+- User friendliness of software
+- Software quality
+- Recognition and rewards for software developers
+- Scholarly archive
+- Software sustainability
+
+What are the reasons and motivations that come to mind for you?
+
+### Mapping motivations
+
+(**NB:** If you are not yet familiar with the FAIR principles for research software, [take a look at the chapter on FAIR software](/fairsoftware) before doing the following exercise.)
+
+The motivations we listed above were important considerations for the development of Software Management Plans as well as the FAIR principles for research software.
+They do not match completely, however.
+Each has its own focus and emphasis.
+
+In the following exercise, we will map the motivations we listed above to the ultimate goals of SMPs and the FAIR principles.
+
+Draw a Venn diagram with two circles: SMP and FAIR:
+
+<img src="media/venn_fairsmp.png" width="400">
+
+Map the motivations listed above to the Venn diagram.
+
+- Which motivations are covered by SMPs, which by FAIR, and which by both?
+- Do you find any motivations that are not covered by either?
+- What does this tell you about the relationship between SMPs and FAIR?
diff --git a/modules/smp/reading.md b/modules/smp/reading.md
@@ -0,0 +1,24 @@
+# Reading material
+
+## Software Management Plans
+
+### Zenodo
+Read in Zenodo about [Practical guide to Software Management Plans](https://zenodo.org/records/7589725)
+
+### Software Sustainability Institute
+Read in SSI Resources Hub about [Writing and using a software management plan](https://www.software.ac.uk/guide/writing-and-using-software-management-plan)
+
+## Overview of practical guides
+There are various practical guides online to the different aspects of software management.
+
+Here is an (incomplete) list:
+
+- [Version control](https://the-turing-way.netlify.app/reproducible-research/vcs.html)
+- [Testing](https://the-turing-way.netlify.app/reproducible-research/testing/testing-guidance.html)
+- [Packaging](https://the-turing-way.netlify.app/reproducible-research/renv/renv-package.html)
+- [Documentation](https://guide.esciencecenter.nl/#/best_practices/documentation)
+  - User
+  - Deployment
+  - Developer
+- [Citation](https://the-turing-way.netlify.app/communication/citable/citable-cff.html#cm-citable-cff)
+- [Software licensing](https://the-turing-way.netlify.app/reproducible-research/licensing/licensing-software.html) and [compatibility](https://the-turing-way.netlify.app/reproducible-research/licensing/licensing-compatibility.html)
diff --git a/modules/smp/media/slides-smp.md → modules/smp/slides-smp.md b/modules/smp/media/slides-smp.md → modules/smp/slides-smp.md
@@ -1,3 +1,11 @@
+# Presentation
+
+## Author
+
+### Date
+
+---
+
 <!-- .slide: data-state="title" -->
 
 # Software Management Plans
@@ -8,7 +16,7 @@
 
 ## Mapping the Via Appia
 
-![Mapping the Via Appia](stories/_smp/viaappia.png)
+![Mapping the Via Appia](media/viaappia.png)
 
 Note:
 The Via Appia was the most important road in the Roman Empire, connecting Rome to Brindisi in the south of Italy, spanning a distance of 540km.
@@ -26,7 +34,7 @@ In this project, research software was used to process the satellite imagery and
 ## The research life cycle
 
 <center>
-<img src="stories/_smp/researchcycle.png" width="60%">
+<img src="media/researchcycle.png" width="60%">
 </center>
 
 Note:
@@ -67,7 +75,7 @@ Ensuring that the software is findable, accessible, usable and understandable is
 
 <!-- .slide: data-state="standard" -->
 
-![Software Needs Maintenance](stories/_smp/maintenance.png)
+![Software Needs Maintenance](media/maintenance.png)
 
 Note:
 Software and code have some unique features.
@@ -148,7 +156,7 @@ Finally, the SMP will allow later verification of plans in a publicly funded pro
 <!-- .slide: data-state="standard" -->
 
 <center>
-<img src="stories/_smp/smpguide.png" width="50%" />
+<img src="media/smpguide.png" width="50%" />
 
 [doi:10.5281/zenodo.7038280](https://doi.org/10.5281/zenodo.7038280)
 
@@ -164,7 +172,7 @@ All past versions and the latest release are available on Zenodo via this DOI.
 <!-- .slide: data-state="standard" -->
 
 <center>
-<img src="stories/_smp/groupedrequirements.png" width="60%" />
+<img src="media/groupedrequirements.png" width="60%" />
 </center>
 
 Note:
@@ -182,7 +190,7 @@ Finally, the guide asks about the *purpose* of the software.
 
 <!-- .slide: data-state="standard" -->
 <center>
-<img src="stories/_smp/purpose.png" width="40%" />
+<img src="media/purpose.png" width="40%" />
 </center>
 
 - What problem does it solve?
@@ -201,7 +209,7 @@ This will help the developers focus on the specific needs of the software.
 <!-- .slide: data-state="standard" -->
 
 <center>
-<img src="stories/_smp/engineering.png" width="30%" />
+<img src="media/engineering.png" width="30%" />
 </center>
 
 - What version control will you use?
@@ -229,7 +237,7 @@ There are many tools that can help with this, and it is important to choose them
 <!-- .slide: data-state="standard" -->
 
 <center>
-<img src="stories/_smp/documentation.png" width="30%" />
+<img src="media/documentation.png" width="30%" />
 </center>
 
 - What documentation will you provide
@@ -251,7 +259,7 @@ In *developer documentation*, instructions on how to modify the software, and ho
 <!-- .slide: data-state="standard" -->
 
 <center>
-<img src="stories/_smp/projectmanagement.png" width="30%" />
+<img src="media/projectmanagement.png" width="30%" />
 </center>
 
 - What license will you use?
@@ -304,7 +312,7 @@ An assessment rubric should accompany the template, indicating per question or f
 
 ## Not all software is equal
 
-![](stories/_smp/softwarespectrum.png)
+![](media/softwarespectrum.png)
 
 Note:
 It is important to realize when making an SMP, that research software comes in many shapes and sizes.
@@ -413,7 +421,7 @@ Addressing what purpose the software serves, how reliable it needs to be, and wh
 <!-- .slide: data-state="standard" -->
 
 <center>
-<img src="stories/_smp/threelevels.png" width="60%">
+<img src="media/threelevels.png" width="60%">
 </center>
 
 Note: