diff --git a/README.md b/README.md
index cc1f1b6..a49510d 100644
--- a/README.md
+++ b/README.md
@@ -88,7 +88,7 @@ If you compare the Python and the Julia script you can see that:
 
 Have a look at the [Examples] that teach you how to construct a full tether model step by step.
 
-## Comparison
+## Overall comparison
 Execution time for a simulation of 10s duration with logging the state every 20ms.
 
 | Testcase                    | Lines of code (LOC) Julia | LOC Python  | Time Julia [ms] | Time Python [ms] |
diff --git a/docs/src/examples.md b/docs/src/examples.md
index 8bcef43..6e3f8a6 100644
--- a/docs/src/examples.md
+++ b/docs/src/examples.md
@@ -1,5 +1,4 @@
-## More examples
-### Mass, attached to a spring damper element
+## Mass, attached to a spring damper element
 From the Julia prompt, run the simulation:
 ```julia
 include("src/Tether_02.jl")
@@ -12,7 +11,7 @@ upwards.
 
 **Julia code:** [Tether_02.jl](src/Tether_02.jl)
 
-### Mass, attached to a non-linear spring damper element
+## Mass, attached to a non-linear spring damper element
 ```julia
 include("src/Tether_03.jl")
 ```
@@ -40,7 +39,7 @@ eqs = vcat(D.(pos)      ~ vel,
 
 The same as Python version: **Python code:** [Tether_03.py](src/Tether_03.py). 
 
-#### Using a callback
+### Using a callback
 By using a callback to detect exactly when the transition from a stiff tether segment to a loose
 tether segment happens we can increase the accuracy of the simulation. **Julia code:** [Tether_03b.jl](src/Tether_03b.jl).
 
@@ -59,7 +58,7 @@ and add the parameter `callback = cb` to the line that calls the solver:
 sol = solve(prob, Rodas5(), dt=dt, abstol=tol, reltol=tol, saveat=ts, callback = cb)
 ```
 
-#### Using a callback with Python
+### Using a callback with Python
 In Python you would have to add the following attribute:
 ```Python
     sw0 = [vel_1[2] > 0] # array of booleans; true means the tether segment is loose (l < l_0)
@@ -90,7 +89,7 @@ As you can see, logging of calculated variables is not
 possible with Assimulo (easy with ModelingToolkit in Julia). You need to re-calculate them
 after the simulation.
 
-#### Multi-segment tether
+## Multi-segment tether
 Using 2D arrays of variables allows to simulate a multi-segment tether:
 ```julia
 @variables pos(t)[1:3, 1:segments+1]  = POS0
@@ -137,7 +136,7 @@ Finally in this example we plot the result dynamically as 2D video. Screenshot:
 ![Tether 2D](docs/images/Tether2d.png)
 
 
-#### Benchmarking
+## Benchmarking
 Using a callback slows the simulation down, but not much. Try it out:
 ```julia
 include("src/Tether_03c.jl")
diff --git a/docs/src/python.md b/docs/src/python.md
index 0a534bc..a80c9b7 100644
--- a/docs/src/python.md
+++ b/docs/src/python.md
@@ -1,11 +1,11 @@
-## Python and Julia in harmony
+# Python and Julia in harmony
 
 Python and Julia play very well together. You could see in the examples above that I am using Matplotlib for plotting, both in Python and in Julia. Julia has a build-in package manager. You can use it install and remove Julia packages, but also to install or remove Python packages. That works like this:
 
-### Using Python packages from Julia
+## Using Python packages from Julia
 There are three options:
 
-#### Option one: 
+### Option one: 
 Use wrapper libraries which exist for a few, very popular Python packages, e.g.
 [PyPlot.jl](https://github.com/JuliaPy/PyPlot.jl) for Matplotlib or [SymPy.jl](https://github.com/JuliaPy/SymPy.jl) for SymPy. You can install them like any other Julia package, e.g.
 ```
@@ -18,7 +18,7 @@ and on the Julia prompt:
 using SymPy
 ```
 
-#### Option two:
+### Option two:
 
 Use PyCall to use Python packages for Julia. This works for all Python packages, but 
 is a little bit less comfortable than option one. Example:
@@ -46,7 +46,7 @@ cd bin
 ```
 to re-build it.
 
-#### Option three:
+### Option three:
 
 Using the package [PythonCall](https://github.com/JuliaPy/PythonCall.jl).
 You cannot use it together with `PyCall`, it is the newer successor of `PyCall`, and it is