From 680ec508c01febadfb14756c49acf1ae5037cf2a Mon Sep 17 00:00:00 2001
From: Michele Nottoli <michele.nottoli@gmail.com>
Date: Tue, 10 Oct 2023 14:14:28 +0200
Subject: [PATCH] Improved clarity.
---
0_Installation.ipynb | 30 ++++++++++--------------------
README.md | 20 ++++++++++----------
2 files changed, 20 insertions(+), 30 deletions(-)
diff --git a/0_Installation.ipynb b/0_Installation.ipynb
index 36cfaf4..8f3b8df 100644
--- a/0_Installation.ipynb
+++ b/0_Installation.ipynb
@@ -22,18 +22,13 @@
"metadata": {},
"source": [
"## Software and material\n",
- "What you need for the workshop (quick overview, step by step instructions are given later):\n",
+ "The course requires various things: a working installation of [Julia 1.9](https://julialang.org/downloads/), [Jupyter](https://jupyter.org/), [IJulia.jl](https://github.com/JuliaLang/IJulia.jl), the course material and various dependencies. To get everything follow these steps:\n",
"\n",
- "- [Julia 1.9](https://julialang.org/downloads/)\n",
- "- [Jupyter](https://jupyter.org/) and [IJulia.jl](https://github.com/JuliaLang/IJulia.jl)\n",
- "- This repository of workshop materials\n",
- "- All required dependencies (Julia packages) for the workshop\n",
- "\n",
- "### Getting Julia\n",
+ "### 1) Getting Julia\n",
"For following the course you will need **Julia 1.9**.\n",
"Julia can be easily obtained in binary form from [Julia downloads](https://julialang.org/downloads/).\n",
"\n",
- "### Getting all the rest\n",
+ "### 2) Getting all the rest\n",
"\n",
"To get the remaining files and dependencies start up `julia` and in the resulting REPL shell, copy and paste the following:\n",
"```julia\n",
@@ -43,7 +38,7 @@
"```\n",
"This [downloads the install.jl script](https://gitlab.mathematik.uni-stuttgart.de/stammbn/julia-seminar/-/raw/main/install.jl?ref_type=heads) and runs it from julia.\n",
"\n",
- "### Getting all the rest (alternative version)\n",
+ "### 2) Getting all the rest (expert version)\n",
"\n",
"As an alternative you can also also run the following commands manually (this requires to have `git` and `julia` available from the commandline): \n",
"```\n",
@@ -52,7 +47,7 @@
"julia install-manual.jl\n",
"```\n",
"\n",
- "### Starting the notebook\n",
+ "### 3) Starting the notebook\n",
"To start the notebook make sure to be in the folder `Julia-seminar` and then run `julia`: an interactive Julia command line will open. In there run this command\n",
"\n",
"```\n",
@@ -72,18 +67,13 @@
"metadata": {},
"source": [
"## Software und Material\n",
- "Was du für das Seminar benötigst (schneller Überblick, detaillierte Anweisungen werden später gegeben):\n",
- "\n",
- "- [Julia 1.9](https://julialang.org/downloads/)\n",
- "- [Jupyter](https://jupyter.org/) und [IJulia.jl](https://github.com/JuliaLang/IJulia.jl)\n",
- "- Dieses Repository mit den Workshop-Materialien\n",
- "- Alle benötigten Abhängigkeiten (Julia-Pakete) für das Seminar\n",
+ "Der Kurs erfordert verschiedene Dinge: eine funktionierende Installation von [Julia 1.9](https://julialang.org/downloads/), [Jupyter](https://jupyter.org/), [IJulia.jl](https://github.com/JuliaLang/IJulia.jl), das Kursmaterial und verschiedene Abhängigkeiten. Um alles zu bekommen, befolgen Sie diese Schritte:\n",
"\n",
- "### Julia herunterladen\n",
+ "### 1) Julia herunterladen\n",
"Um dem Kurs zu folgen, benötigst du **Julia 1.9**.\n",
"Julia kann leicht in binärer Form von den [Julia-Downloads](https://julialang.org/downloads/) bezogen werden.\n",
"\n",
- "### Alles andere herunterladen\n",
+ "### 2) Alles andere herunterladen\n",
"\n",
"Um die verbleibenden Dateien und Abhängigkeiten zu erhalten, starte `julia` und kopiere im resultierenden REPL-Shell folgenden Code:\n",
"```julia\n",
@@ -93,7 +83,7 @@
"```\n",
"Das [lädt das install.jl-Skript herunter](https://gitlab.mathematik.uni-stuttgart.de/stammbn/julia-seminar/-/raw/main/install.jl?ref_type=heads) und führt es in Julia aus.\n",
"\n",
- "### Den Rest bekommen (alternative Version)\n",
+ "### 2) Den Rest bekommen (Experten-Version)\n",
"\n",
"Als Alternative können Sie auch die folgenden Befehle manuell ausführen (dies setzt voraus, dass `git` und `julia` von der Kommandozeile aus verfügbar sind):\n",
"```\n",
@@ -102,7 +92,7 @@
"julia install-manual.jl\n",
"```\n",
"\n",
- "### Starten des Notebooks\n",
+ "### 3) Starten des Notebooks\n",
"Um das Notebook zu starten, stellen Sie sicher, dass Sie sich im Ordner `Julia-seminar` befinden, und führen Sie dann `julia` aus: Eine interaktive Julia-Befehlszeile wird geöffnet. Führen Sie darin folgenden Befehl aus:\n",
"\n",
"```\n",
diff --git a/README.md b/README.md
index f6408fb..5bd1c39 100644
--- a/README.md
+++ b/README.md
@@ -6,18 +6,13 @@ The course material is adapted from two sources:
- the book [ThinkJulia](https://benlauwens.github.io/ThinkJulia.jl/latest/book.html) from Allen Downey and Ben Lauwens ([Creative Commons Attribution-NonCommercial 3.0 Unported license](https://creativecommons.org/licenses/by-nc/3.0/deed.en)).
## Software and material
-What you need for the workshop (quick overview, step by step instructions are given later):
+The course requires various things: a working installation of [Julia 1.9](https://julialang.org/downloads/), [Jupyter](https://jupyter.org/), [IJulia.jl](https://github.com/JuliaLang/IJulia.jl), the course material and various dependencies. To get everything follow these steps:
-- [Julia 1.9](https://julialang.org/downloads/)
-- [Jupyter](https://jupyter.org/) and [IJulia.jl](https://github.com/JuliaLang/IJulia.jl)
-- This repository of workshop materials
-- All required dependencies (Julia packages) for the workshop
-
-### Getting Julia
+### 1) Getting Julia
For following the course you will need **Julia 1.9**.
Julia can be easily obtained in binary form from [Julia downloads](https://julialang.org/downloads/).
-### Getting all the rest
+### 2) Getting all the rest
To get the remaining files and dependencies start up `julia` and in the resulting REPL shell, copy and paste the following:
```julia
@@ -27,7 +22,7 @@ include(script)
```
This [downloads the install.jl script](https://gitlab.mathematik.uni-stuttgart.de/stammbn/julia-seminar/-/raw/main/install.jl?ref_type=heads) and runs it from julia.
-### Getting all the rest (alternative version)
+### 2) Getting all the rest (expert version)
As an alternative you can also also run the following commands manually (this requires to have `git` and `julia` available from the commandline):
```
@@ -36,7 +31,7 @@ cd Julia-seminar
julia install-manual.jl
```
-### Starting the notebook
+### 3) Starting the notebook
To start the notebook make sure to be in the folder `Julia-seminar` and then run `julia`: an interactive Julia command line will open. In there run this command
```
@@ -49,6 +44,11 @@ If you are facing issues, check out
the [great troubleshooting section](https://carstenbauer.github.io/WorkshopWizard.jl/dev/troubleshooting/)
from the WorkshopWizard package by Carsten Bauer (which is being used by `install.jl`).
+### Troubleshooting
+If you are facing issues, check out
+the [great troubleshooting section](https://carstenbauer.github.io/WorkshopWizard.jl/dev/troubleshooting/)
+from the WorkshopWizard package by Carsten Bauer (which is being used by `install.jl`).
+
## For Developers: Setting Up `pre-commit`
[`pre-commit`](https://pre-commit.com/) is a framework that helps to manage and maintain pre-commit hooks to ensure that your code adheres to a consistent style, prevents errors, and adheres to other quality assurance checks.
--
GitLab