diff --git a/modules/softwaremanagementplans/practicalguide.md b/modules/softwaremanagementplans/practicalguide.md index 8b4041e3..3ec07e6b 100644 --- a/modules/softwaremanagementplans/practicalguide.md +++ b/modules/softwaremanagementplans/practicalguide.md @@ -1,7 +1,7 @@ --- title: Practical Guide type: reading -order: 2 +order: 3 --- @@ -25,4 +25,4 @@ 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. \ No newline at end of file +- Be able to explain the importance of a software management plan for software sustainability. diff --git a/modules/softwaremanagementplans/reading.md b/modules/softwaremanagementplans/reading.md index ae630f6a..fb1331ce 100644 --- a/modules/softwaremanagementplans/reading.md +++ b/modules/softwaremanagementplans/reading.md @@ -1,7 +1,7 @@ --- title: Reading material type: reading -order: 5 +order: 6 --- # Reading material @@ -27,4 +27,4 @@ Here is an (incomplete) list: - 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) \ No newline at end of file +- [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/softwaremanagementplans/requirements.md b/modules/softwaremanagementplans/requirements.md new file mode 100644 index 00000000..84c796ff --- /dev/null +++ b/modules/softwaremanagementplans/requirements.md @@ -0,0 +1,77 @@ +--- +title: SMP requirements +type: info +order: 2 +--- + + + +## **Purpose** +The software's purpose is the most important aspect of the SMP. + +It allows you to be clear about the problem it addresses, and who the software is aimed at, as well as set boundaries on its scope. +Addressing the limitations of the software, as well as the advantages it will provide, help determine its scope. +This will help the developers focus on the specific needs of the software. + + + +## **Engineering** +is related to building the software + +#### **Version Control** +has a myriad of benefits: it allows keeping track of history and provenance, can support experimentation and collaboration, and is crucial for the identification of specific versions of the software. + +#### **Testing** +ensures that software continues to work as intended. +There are many different approaches to this: units of code can be tested in unit tests; entire workflows can be verified in integration tests; acceptance tests can be created to ensure specific requirements are met; regression testing can be done to ensure new changes do not break existing functionality; and so on. +Deciding whether and if so what testing will be implemented is an important element of the SMP. + +#### **Packaging** +is important for the distribution of software. The format in which the software will be distributed is an important decision that should be made early on. + +#### **Code Quality** +should be addressed: what standards will be adhered to, and how will they be measured and supported? +There are many tools that can help with this, and it is important to choose them early on to maintain consistent code quality throughout the project. + + + +## **Documentation** +is an important component of software, and should be tailored to different audiences. + +#### **User Documentation** +the software's function should be explained, and instructions on how to use it should be provided. + +#### **Developer Documentation** +instructions on how to modify the software, and how to contribute to the project should be provided. + +#### **Deployment Documentation** +explains any system requirements (such as dependencies) for deploying the software, and installation and testing instructions. + + + +## **Project Management** +addresses various conditions for the software's long-term sustainability and re-use. + +#### **License** +Any reusable software should have an appropriate license, which is an important early decision. + +#### **Maintenance** +Who will maintain the software and for how long? +How actively will user concerns be addressed? +How much time will this take? +How and when will it be retired? + +#### **Citation** +How will you collect information about its use? What DOI will you use for this? + +#### **Repository** +where will the software be deposited and how accessible will it be? +Users should be able to obtain a functional copy of the software. + +#### **Resources** +What resources - human, infrastructure, financial - will be needed, and when? + +#### **Risk Analysis** +Are there privacy or security concerns? +Is there potential for vendor lock, or other considerations for future reliability and reuse? +What are the consequences of software failure and how will these be mitigated? diff --git a/modules/softwaremanagementplans/slides-smp.md b/modules/softwaremanagementplans/slides-smp.md index 0770aecc..642448de 100644 --- a/modules/softwaremanagementplans/slides-smp.md +++ b/modules/softwaremanagementplans/slides-smp.md @@ -139,57 +139,7 @@ All past versions and the latest release are available on Zenodo via this DOI. Note: -In the practical guide, the core requirements for an SMP are listed, and grouped into four categories. - - -**Purpose:** -The software's purpose is the most important aspect of the SMP. - -It allows you to be clear about the problem it addresses, and who the software is aimed at, as well as set boundaries on its scope. -Addressing the limitations of the software, as well as the advantages it will provide, help determine its scope. -This will help the developers focus on the specific needs of the software. - - -**Engineering:** -*Version control* has a myriad of benefits: it allows keeping track of history and provenance, can support experimentation and collaboration, and is crucial for the identification of specific versions of the software. - -*Testing* ensures that software continues to work as intended. -There are many different approaches to this: units of code can be tested in unit tests; entire workflows can be verified in integration tests; acceptance tests can be created to ensure specific requirements are met; regression testing can be done to ensure new changes do not break existing functionality; and so on. -Deciding whether and if so what testing will be implemented is an important element of the SMP. - -*Packaging* is important for the distribution of software. -The format in which the software will be distributed is an important decision that should be made early on. - -*Code quality* should be addressed: what standards will be adhered to, and how will they be measured and supported? -There are many tools that can help with this, and it is important to choose them early on to maintain consistent code quality throughout the project. - - -**Documentation:** -Documentation is an important component of software, and should be tailored to different audiences. - -In *user documentation*, the software's function should be explained, and instructions on how to use it should be provided. - -In *developer documentation*, instructions on how to modify the software, and how to contribute to the project should be provided. - -*Deployment documentation* explains any system requirements (such as dependencies) for deploying the software, and installation and testing instructions. - - -**Project Management:** - -The project management focus is broad, and addresses various conditions for the software's long-term sustainability and re-use. - -Any reusable software should have an appropriate *license*, which is an important early decision. - -The *maintenance* of the software should be addressed in an SMP: who will maintain it, and for how long? -How and when will it be retired? - -Plan the *citation* of the software: how will you collect information about its use? What DOI will you use for this? - -The *repository* where the software will be deposited is preferably publicly accessible, and should allow users to obtain a functional copy of the software. - -What *resources* — human, infrastructure, financial - will be needed, and when? - -Finally, a *risk analysis* should be performed: for instance, are there privacy or security concerns? Is there potential for vendor lock, or other considerations for future reliability and reuse? +In the practical guide, the core requirements for an SMP are listed, and grouped into four categories. See xxx for more details. diff --git a/modules/softwaremanagementplans/smpvsfair.md b/modules/softwaremanagementplans/smpvsfair.md index b29e7a27..f390f753 100644 --- a/modules/softwaremanagementplans/smpvsfair.md +++ b/modules/softwaremanagementplans/smpvsfair.md @@ -1,7 +1,7 @@ --- title: SMP vs FAIR type: exercise -order: 4 +order: 5 --- ## SMP vs FAIR @@ -40,4 +40,4 @@ 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? \ No newline at end of file +- What does this tell you about the relationship between SMPs and FAIR? diff --git a/modules/softwaremanagementplans/templatebuilding.md b/modules/softwaremanagementplans/templatebuilding.md index 737189b5..e46b2889 100644 --- a/modules/softwaremanagementplans/templatebuilding.md +++ b/modules/softwaremanagementplans/templatebuilding.md @@ -1,7 +1,7 @@ --- title: Build a Template type: exercise -order: 3 +order: 4 --- # Build your own Software Management Plan template