Rework learning goals and make them consistent (#190)

* Fix minor things in contribution guidelines and README * Rework learning goals * Update 02_virtualization_and_containers/README.md Co-authored-by: Gerasimos Chourdakis <[email protected]> * Update 03_building_and_packaging/README.md Co-authored-by: Gerasimos Chourdakis <[email protected]> * Update 04_documentation/README.md Co-authored-by: Gerasimos Chourdakis <[email protected]> * Update 03_building_and_packaging/README.md Co-authored-by: Gerasimos Chourdakis <[email protected]> * Update 02_virtualization_and_containers/README.md Co-authored-by: Gerasimos Chourdakis <[email protected]> --------- Co-authored-by: Gerasimos Chourdakis <[email protected]>
Simulation-Software-Engineering · Oct 30, 2024 · 6415777 · 6415777
1 parent 8ba5d5b
commit 6415777
Show file tree

Hide file tree

Showing 6 changed files with 25 additions and 32 deletions.
diff --git a/02_virtualization_and_containers/README.md b/02_virtualization_and_containers/README.md
@@ -2,11 +2,10 @@
 
 Learning goals:
 
-- Understand the difference between virtualization and containers.
-- Have clarity on when and how to use virtual machines and/or containers.
-- Work with virtual machines (VirtualBox) and manage them with Vagrant.
-- Work with containers with Docker (and Singularity).
-- Know how to set up own containers tailored to your requirements.
+- Name differences between virtualization and containers and name use cases for each.
+- Create and modify virtual machines with VirtualBox and generate them with Vagrant.
+- Create and manage Docker containers.
+- Name containerization technologies beyond Docker and name their main differences.
 
 | Duration | Content |
 | --- | --- |

diff --git a/03_building_and_packaging/README.md b/03_building_and_packaging/README.md
@@ -2,12 +2,12 @@
 
 Learning goals:
 
-- What is code packaging and which technologies are available to package code
-- How is Python code packaged for uploading to PyPI and installation with pip
-- What are libraries, how can they be used
-- How can codes be build and dependencies handled with Make and CMake
-- How are software packages provided via common packaging approaches (pip, apt, npm)
-- How are software packages provided for high-performance computing (Spack, EasyBuild)
+- Explain why software is packaged.
+- Create Python packages, publish on PyPI, and install with pip.
+- Understand the difference between static and dynamic libraries and common ways of installation on Linux.
+- Build C++ software and handle dependencies with Make and CMake.
+- Package C++ software with CPack and create Debian packages.
+- Create Spack packages, e.g., for high-performance computing systems with restricted access rights.
 
 | Duration | Content |
 | --- | --- |

diff --git a/04_documentation/README.md b/04_documentation/README.md
@@ -3,12 +3,11 @@
 Learning goals:
 
 - Be aware that documentation is crucial in RSE.
-- Understand that there is a difference between documentation and **good documentation**.
-- Know the purpose and basic structure of several **standard documentation building blocks** (README, commit message, changelog, ...).
-- Read, write, and convert between common lightweight markup languages.
+- Understand that there is a difference between documentation and *good* documentation.
+- Know the purpose and basic structure of several standard documentation building blocks (README, commit message, changelog, ...).
+- Read and write common lightweight markup languages and generate PDF files from them.
 - Know about the most important website generators and hosting options for research software documentation.
 
-
 | Duration | Content |
 | --- | --- |
 | 25 minutes | [`markup_languages_slides.md`](https://github.com/Simulation-Software-Engineering/Lecture-Material/blob/main/04_documentation/markup_languages_slides.md)|

diff --git a/05_testing_and_ci/README.md b/05_testing_and_ci/README.md
@@ -3,19 +3,14 @@
 Learning goals:
 
 - Justify the effort of developing testing infrastructure for simulation software.
-- Discern the concepts of unit testing, integration testing and regression testing with the perspective of simulation software.
+- Discern the concepts of unit testing, integration testing, and regression testing with the perspective of simulation software.
 - Work with the Python testing frameworks `pytest` and `unittest`.
-- Name and explain common workflows to automate in RSE.
-- Explain the differences between the various continuous methodologies.
-- Explain why automation is crucial in RSE.
-- Write basic automation scripts for GitHub Actions.
-- Read basic automation scripts for GitLab CI/CD.
-- Name and roughly explain the necessary steps to host GitLab Runners yourself.
 - Write simple tests for C++ toy codes with `Boost.Test`.
 - Know about general concepts of test frameworks such as fixtures and decorators.
+- Name and explain common workflows to automate in RSE.
+- Write basic automation scripts for GitHub Actions.
+- Read basic automation scripts for GitLab CI/CD and explain the necessary steps to host GitLab Runners yourself.
 - Use CTest to call tests from CMake.
-- Know about common challenges of unit and integration tests in real simulation software through preCICE as an example.
-- Explain how `Boost.Test`, CMake, and GitHub Actions can work together.
 
 | Duration | Content |
 | --- | --- |

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,10 +1,10 @@
-# Contribution guide
+# Contribution Guide
 
 We appreciate all kinds of contributions to this project. This document gives you some information on how to contribute to the project.
 
-## How can I contribute?
+## How Can I Contribute?
 
-- We suggest to follow the common workflow based on issues and pull requests. In the issue, you should describe the problem. Based on this discussion one can create a pull request that should solve the issue.
+- We suggest to follow the common workflow based on issues and pull requests. In the issue, you should describe the problem. Based on this discussion, one can create a pull request that should solve the issue.
 - A good issue describes what is wrong and why it is wrong. Ideally, one has already a suggestion on how to fix the problem, but the suggestions is not mandatory.
 - A good pull request should refer to the issue and thus to the problem that it should solve. Explain what the pull request does and how it addresses the problem/issue. If you still work on a new feature or a fix, you can open a pull request and mark is as draft. Once you consider the work done, please mark it as ready for review and request a reviewer. We will give feedback and eventually merge the pull request.
 - We enforce consistency of the formatting via automatic style checking. When marking a pull request as ready for review, please make sure that all checks pass successfully.
@@ -15,7 +15,7 @@ We appreciate all kinds of contributions to this project. This document gives yo
 
 Please follow the guidelines in `docs/styleguide.md`.
 
-## Licensing of contributed material
+## Licensing of Contributed Material
 
 By contributing to this project you agree that your contributions will be covered by the same license of as the project. More information about the license can be found in the file `LICENSE`.
 
diff --git a/README.md b/README.md
@@ -4,14 +4,14 @@
 [![PDFs](https://github.com/Simulation-Software-Engineering/lecture-materials/actions/workflows/create-pdfs-from-markdown.yml/badge.svg)](https://github.com/Simulation-Software-Engineering/Lecture-Material/actions/workflows/create-pdfs-from-markdown.yml)
 [![CC BY 4.0][cc-by-shield]][cc-by]
 
-Material of the Simulation Software Engineering lecture. There are different way how to get an overview:
+Material of the Simulation Software Engineering lecture. There are different ways how to get an overview:
 
 - Look at `timetable.md` of the [current course](https://github.com/Simulation-Software-Engineering/Lecture-Material/blob/main/timetable.md) or [a previous course](https://github.com/Simulation-Software-Engineering/Lecture-Material/tree/main/00_organization/wt2223/timetable.md), or
 - Look at the `README.md` files of each chapter / folder.
 
 Please note that we update the material over the course of each semester.
 
-## List of chapters
+## List of Chapters
 
 1. [Version Control](https://github.com/Simulation-Software-Engineering/Lecture-Material/tree/main/01_version_control)
 2. [Virtualization and Containers](https://github.com/Simulation-Software-Engineering/Lecture-Material/tree/main/02_virtualization_and_containers)
@@ -22,15 +22,15 @@ Please note that we update the material over the course of each semester.
 
 ## Linting
 
-The markdown files can be checked using [markdownlint](https://github.com/markdownlint/markdownlint/). Once the linter is installed one can run it locally from the root of this repository using
+The markdown files can be checked using [markdownlint](https://github.com/markdownlint/markdownlint/). Once the linter is installed, run it locally from the root of this repository using
 
 ```
 mdl .
 ```
 
 It will automatically read the markdownlint configuration of this repository. The linter is configured in the files `.mdl.rb` and `.mdlrc`. The majority of the configuration is done in `.mdl.rb`.
 
-## Third-party content
+## Third-Party Content
 
 In several parts of the material, we use content from