diff --git a/docs/0-intro.md b/docs/0-intro.md
new file mode 100644
index 0000000000000000000000000000000000000000..75fd77956c39f3655a22cce1d74ad870f731d8ac
--- /dev/null
+++ b/docs/0-intro.md
@@ -0,0 +1,120 @@
+# Basics of Sustainable Software Engineering in Julia
+
+Sustainable Software Engineering is an essential aspect of modern software development, focusing on practices that ensure long-term efficiency, maintainability, and scalability of software projects. This introduction covers the core principles of Sustainable Software Engineering, including the use of Git for version control, the importance of testing, the role of documentation, and the specifics of applying these practices in the Julia programming language.
+
+## Basic Introduction to Linux Shell
+
+### Overview
+The Linux Shell is a command-line interface (CLI) used in Linux operating systems. It allows users to interact with the system by typing commands, rather than using a graphical interface.
+
+### Accessing the Shell on UNIX (+maxOS)
+- **Terminal:** Open the terminal application from your Linux desktop environment.
+- **Keyboard Shortcut:** Often Ctrl+Alt+T.
+
+### Accessing the Shell on UNIX (+maxOS)
+- **Git Bash:** Has most of the common tools included.
+- Other options: PowerShell, WSL, ...
+
+### Basic Commands
+1. **`pwd`** - Print Working Directory. Shows the current directory you are in.
+2. **`ls`** - Lists files and directories in the current directory.
+   - **`ls -l`**: Detailed list.
+   - **`ls -a`**: Includes hidden files.
+3. **`cd`** - Change Directory.
+   - **`cd ..`**: Move one directory up.
+   - **`cd /path/to/directory`**: Move to a specific directory.
+4. **`mkdir`** - Make a new directory.
+5. **`rmdir`** - Remove an empty directory.
+6. **`touch`** - Create a new empty file.
+7. **`cp`** - Copy files or directories.
+   - **`cp source destination`**: Copy source to destination.
+8. **`mv`** - Move or rename files or directories.
+9. **`rm`** - Remove files or directories.
+   - **`rm -r`**: Recursive remove (for directories).
+10. **`echo`** - Display a line of text.
+11. **`cat`** - Concatenate and display file content.
+12. **`grep`** - Search text using patterns.
+13. **`man`** - Display the manual of a command.
+
+### System Information
+- **`df`**: Report file system disk space usage.
+- **`top`**: Display Linux tasks.
+
+### Tips
+- Use the **Tab** key for auto-completing commands and file names.
+- Use **up and down arrow keys** to navigate through command history.
+
+
+## Introduction to Markdown
+
+### What is Markdown?
+Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world's most popular markup languages.
+
+### Why Use Markdown?
+- **Simplicity**: Markdown is easy to learn and use.
+- **Portability**: Markdown files are plain text, so they're readable on any device.
+- **Flexibility**: You can convert Markdown to HTML, PDF, and more.
+
+### Basic Syntax
+
+#### Headings
+Use `#` for headings. More `#`s mean smaller headings.
+
+```markdown
+# Heading 1
+## Heading 2
+#### Heading 3
+```
+
+#### Emphasis
+- *Italic*: Use `*` or `_` around the text.
+- **Bold**: Use `**` or `__` around the text.
+
+```markdown
+*Italic text*
+**Bold text**
+```
+
+#### Lists
+For unordered lists, use `*`, `+`, or `-`. For ordered lists, simply number them.
+
+```markdown
+- Item 1
+- Item 2
+  - Sub Item 1
+  - Sub Item 2
+```
+
+#### Links and Images
+- Links: `[Text](URL)`
+- Images: `![Alt Text](URL)`
+
+```markdown
+[Google](https://www.google.com)
+![Image](image_url.jpg)
+```
+
+#### Code
+- Inline code: Use backticks ` `` `, `Inline code`
+- Code blocks: Use triple backticks with optional language identifier
+```julia
+1+1
+# 2
+```
+
+#### Blockquotes
+Use `>` for block quotes.
+
+```markdown
+> This is a blockquote.
+```
+
+
+## Integrated Development Environment (IDE)
+- **VS Code**: All-in-one solution, quite good for Julia programming
+TOOD: Insert picture explaning different workspaces
+- Other choices: Vim, Emacs, Atom, Jetbrains, ...
+
+## Further Reading/References
+
+- CLick PDF slides in https://thsn.dev/blog/publishing-reproducable-numerics
diff --git a/docs/1_git.md b/docs/1-git.md
similarity index 82%
rename from docs/1_git.md
rename to docs/1-git.md
index 315d067d7ec777795bdf65aab064bbfe2bff6e9e..8d85f5f662eedbebba0942a303f68862cd8115e6 100644
--- a/docs/1_git.md
+++ b/docs/1-git.md
@@ -20,6 +20,10 @@ Git is a distributed version control system designed to handle everything from s
 - `git push`: Pushes commits to a remote repository.
 - `git pull`: Fetches and merges changes from a remote repository.
 
+![Alt text](./figs//git-remote.png)
+
+Source: https://merely-useful.tech/py-rse/figures/git-cmdline/git-remote.png
+
 ## Getting Started
 
 To start using Git, first [install it](https://git-scm.com/downloads) on your machine. Then, set up your user name and email with the following commands:
@@ -27,4 +31,12 @@ To start using Git, first [install it](https://git-scm.com/downloads) on your ma
 ```bash
 git config --global user.name "Your Name"
 git config --global user.email "your.email@example.com"
+```
+
+## Further reading
+- https://aeturrell.github.io/coding-for-economists/wrkflow-version-control.html
+- https://merely-useful.tech/py-rse/git-cmdline.html
 
+TODO
+Addd some images to visualize
+Add further reading
diff --git a/docs/2-julia_project_structure.md b/docs/2-julia_project_structure.md
new file mode 100644
index 0000000000000000000000000000000000000000..c60efd0f030569bc41cc047d350b08c8f31daa6f
--- /dev/null
+++ b/docs/2-julia_project_structure.md
@@ -0,0 +1,91 @@
+# Julia Project Structure
+
+This lecture focuses on the structure and management of Julia-specific projects. We will cover how to create a project using the Package Manager, the purpose of various directories and files, and best practices for maintaining a Julia project.
+
+
+## Creating a Project Using Package Manager
+
+- Steps to create a new Julia project
+- Using the Julia REPL and the Package Manager (`Pkg`)
+- Example command:
+
+```
+julia> # Press `]` button to go to pkg mode
+pkg> generate MyProject
+```
+
+## Key Folders in a Julia Project
+
+### `src` Folder
+
+- The `src` folder: Where the source code lives
+- Structure and naming conventions for source files
+
+### `docs` Folder
+
+- Purpose of the `docs` folder: Documentation of the project
+- Tools for generating documentation in Julia, e.g., Documenter.jl
+
+### `examples` Folder
+
+- The `examples` folder: Contains example scripts and notebooks
+- Demonstrating usage and features of the project
+
+## README File
+
+- Importance of a `README.md` file in a project
+- Key elements to include: project description, installation instructions, usage examples, contact info, ...
+
+## Project.toml and Manifest.toml
+
+- `Project.toml`: Managing project dependencies and environment settings
+- `Manifest.toml`: Detailed state of the environment for reproducibility
+- Understanding the role of these files in dependency management and version control
+
+### TOML
+TOML (Tom's Obvious, Minimal Language) is a simple, easy-to-read configuration file format. Designed by Tom Preston-Werner in 2013, it aims to be more human-readable and writable than formats like XML or JSON.
+```toml
+# This is a TOML document
+
+title = "TOML Example"
+
+[owner]  # a table => key-value pairs
+name = "Tom Preston-Werner"
+dob = 1979-05-27T07:32:00-08:00
+
+[database]  # another table
+enabled = true
+ports = [ 8000, 8001, 8002 ]
+data = [ ["delta", "phi"], [3.14] ]
+temp_targets = { cpu = 79.5, case = 72.0 }
+
+[servers]
+
+[servers.alpha]
+ip = "10.0.0.1"
+role = "frontend"
+
+[servers.beta]
+ip = "10.0.0.2"
+role = "backend"
+```
+
+## Optional Files
+
+### LICENSE
+
+- Adding a `LICENSE` file: Types of licenses and their implications
+
+### CODE_OF_CONDUCT
+
+- The importance of a `CODE_OF_CONDUCT.md` file
+- Fostering an inclusive and respectful community
+
+---
+
+In conclusion, a well-structured Julia project not only facilitates development and collaboration but also ensures the reproducibility and integrity of the project. The use of `Project.toml` and `Manifest.toml` files in conjunction with the Julia Package Manager plays a crucial role in managing dependencies and maintaining a consistent project environment.
+
+Consider this repository as template/good-practise!
+
+For further reading and resources, refer to the [Julia documentation](https://docs.julialang.org/).
+
diff --git a/docs/3-julia_documentation.md b/docs/3-julia_documentation.md
new file mode 100644
index 0000000000000000000000000000000000000000..549fb7c7ec4c1f902f3f4cf128d817f46f5dd9e0
--- /dev/null
+++ b/docs/3-julia_documentation.md
@@ -0,0 +1,92 @@
+# Julia Documentation
+
+In this lecture, we'll explore how to effectively document Julia code. We'll cover the use of doc strings, introduce Documenter.jl for creating comprehensive documentation, and discuss how to build and host a documentation website.
+
+## Doc Strings in Julia
+
+### Basics of Doc Strings
+
+- What are doc strings and why they are important
+- Basic syntax for writing doc strings in Julia
+
+### Advanced Features in Doc Strings
+
+- Including mathematical expressions using LaTeX syntax
+- Adding code examples within doc strings
+- Documenting function signatures for clarity
+- Best practices for writing informative and clear doc strings
+
+## Code Example: Writing a Doc String
+
+Here's a simple example of how to write a doc string in Julia:
+
+```julia
+"""
+    myFunction(x, y)
+
+Compute the sum of `x` and `y`.
+
+# Arguments
+- `x::Int`: The first integer
+- `y::Int`: The second integer
+
+# Examples
+```julia
+julia> myFunction(2, 3)
+5
+"""
+function myFunction(x::Int, y::Int)
+return x + y
+end
+```
+
+
+This example shows how to document a function's purpose, its arguments, and provide a usage example.
+
+## Introduction to Documenter.jl
+
+Documenter.jl is a tool for producing documentation in Julia. We'll look at how to set it up and use it to generate high-quality documentation for your projects.
+
+### Setting Up Documenter.jl
+
+- Installing Documenter.jl
+- Basic setup and configuration
+
+### Creating an Index with Documenter.jl
+
+- Organizing your documentation structure
+- Writing an index.md file to serve as the entry point
+
+## Including Additional Markdown Files
+
+- How to integrate additional markdown files into your documentation
+- Structuring and linking various parts of the documentation for better navigation
+
+## Rendering Examples Automatically
+
+- Utilizing Documenter.jl to automatically execute and render code examples
+- Ensuring that examples in the documentation remain up-to-date and functional
+
+## Inspecting the resulting index.html
+
+- Generating the HTML documentation locally
+- Tips for inspecting and testing the `index.html` file
+
+## Building a Documentation Website
+
+### Hosting Documentation Files
+
+- Options for hosting the build files to create a publicly accessible documentation website
+- Platforms like GitHub Pages and ReadTheDocs
+
+### Continuous Integration for Documentation Updates
+
+- Setting up CI workflows to automatically update documentation
+
+---
+
+To conclude, effective documentation is crucial for any Julia project. Utilizing doc strings and Documenter.jl can greatly enhance the usability and accessibility of your code. Remember, good documentation is as important as the code itself!
+
+For more details, visit the [Documenter.jl documentation](https://juliadocs.github.io/Documenter.jl/stable/).
+
+
diff --git a/docs/4-julia_testing.md b/docs/4-julia_testing.md
new file mode 100644
index 0000000000000000000000000000000000000000..e928b9388b36d79c78d0251609b1517034b6db88
--- /dev/null
+++ b/docs/4-julia_testing.md
@@ -0,0 +1,92 @@
+
+# Testing in Julia
+
+This lecture aims to provide a comprehensive guide on testing practices in Julia. We will explore the importance of unit tests, delve into coverage aspects, and discuss the integration of automatic testing using continuous integration (CI) tools.
+
+## Importance of Testing
+
+- Why testing is crucial in software development.
+- Types of tests: Unit tests, integration tests, etc.
+
+## Unit Tests in Julia
+
+- Overview of unit testing in Julia.
+- Using the `Test` standard library.
+
+### Writing Unit Tests
+
+- Basic structure of a unit test.
+- Assertions: `@test`, `@test_throws`, `@testset`, etc.
+
+### Example: Unit Test Tutorial
+
+Let's create a simple function and write tests for it:
+
+#### The Function
+
+```julia
+function add(a, b)
+    return a + b
+end
+```
+
+#### Test File
+
+Create a file named `test_add.jl`:
+
+```julia
+using Test
+include("add.jl") # Include the file containing the `add` function
+
+@testset "Addition Tests" begin
+    @test add(2, 2) == 4
+    @test add(-1, 1) == 0
+    @test add(0, 0) == 0
+    @test_throws DomainError add("a", "b")
+end
+```
+
+This example demonstrates basic unit testing by checking various scenarios for the `add` function.
+
+## Invoking the Written Tests
+
+### Running Tests Locally
+
+Once you have written your tests, it's important to know how to run them to check if your code behaves as expected.
+
+#### Using Julia's Interactive Session (REPL)
+
+1. **Start Julia's REPL**: Open a terminal and run `julia` to start the interactive session.
+2. **Activate the Project**: If your project has a specific environment, activate it by using `using Pkg; Pkg.activate("path_to_your_project")`.
+3. **Run the Tests**: Use `Pkg.test()` to run all tests in the test directory of the project.
+
+#### Using the Command Line
+
+Alternatively, you can run your tests directly from the command line without entering the REPL:
+
+- Navigate to your project directory.
+- Run `julia --project=@. -e 'using Pkg; Pkg.test()'`.
+
+This command will execute all tests defined in your project's `test` directory.
+
+TODO: Add example output.
+
+## Test Coverage
+
+### Understanding Test Coverage
+
+- What is test coverage and why it matters.
+- Tools for measuring test coverage in Julia, e.g., Codecov or Coveralls.
+
+### Optional: Incorporating Coverage into Tests
+
+- Adding coverage metrics to your test suite.
+- Interpreting coverage reports to improve test quality.
+
+## Optional: Automatic Testing with Continuous Integration
+
+- Using CI for automatic testing.
+
+## Further reading
+
+- For more detailed information, you can refer to the [Julia documentation on testing](https://docs.julialang.org/en/v1/stdlib/Test/).
diff --git a/docs/9-todo.md b/docs/9-todo.md
new file mode 100644
index 0000000000000000000000000000000000000000..c02402354a8da55ffe7cbb94f54f0f330ab0de40
--- /dev/null
+++ b/docs/9-todo.md
@@ -0,0 +1,3 @@
+# TODO
+- see other course if something is missing
+- add some exercises for students
diff --git a/docs/figs/git-remote.png b/docs/figs/git-remote.png
new file mode 100644
index 0000000000000000000000000000000000000000..337ddadbf137bdbf68d98f10d9cd759448f89dc4
Binary files /dev/null and b/docs/figs/git-remote.png differ