From 57de78a4488eaab63e04ae8bbbc2e477bb5aea03 Mon Sep 17 00:00:00 2001
From: Lars Reimann <mail@larsreimann.com>
Date: Sat, 13 Apr 2024 12:08:01 +0200
Subject: [PATCH] docs: work on installation

---
 docs/getting-started/first-program.md |  3 ++
 docs/getting-started/installation.md  | 52 ++++++++++++++++++++++-----
 docs/mkdocs.yml                       |  1 +
 docs/pipeline-language/README.md      |  3 +-
 4 files changed, 48 insertions(+), 11 deletions(-)
 create mode 100644 docs/getting-started/first-program.md

diff --git a/docs/getting-started/first-program.md b/docs/getting-started/first-program.md
new file mode 100644
index 000000000..2bb9a78d2
--- /dev/null
+++ b/docs/getting-started/first-program.md
@@ -0,0 +1,3 @@
+# Your First Safe-DS Program
+
+TODO
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index b50edfb55..206d452ea 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -1,12 +1,46 @@
 # Installation
 
-1. Get the latest extension for [Visual Studio Code](https://code.visualstudio.com/) from the
-   [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=safe-ds.safe-ds). This sets up a
-   complete _development environment_ for Safe-DS programs.
-2. To _execute_ Safe-DS programs, the [Safe-DS Runner](https://github.com/Safe-DS/Runner) has to be installed and
-   configured additionally:
+1. Install [Visual Studio Code](https://code.visualstudio.com/).
+2. Install the latest [Safe-DS extension](https://marketplace.visualstudio.com/items?itemName=safe-ds.safe-ds) for
+   Visual Studio Code to set up a complete development environment for Safe-DS programs.
+3. Install the [Safe-DS runner](https://github.com/Safe-DS/Runner) to be able to execute Safe-DS programs:
     1. Install [Python](https://www.python.org/) (3.11 or 3.12).
-    2. Run `pip install "safe-ds-runner>=0.10.0,<0.11.0"` in a command line to download the latest matching Runner version
-       from [PyPI](https://pypi.org/project/safe-ds-runner/).
-    3. If the Visual Studio Code extension cannot start the runner, adjust the setting `safe-ds.runner.command`.
-       Enter the absolute path to the Runner executable.
+    2. Run `pip install "safe-ds-runner>=0.10.0,<0.11.0"` in a command line to download the latest matching runner
+       version from [PyPI](https://pypi.org/project/safe-ds-runner/).
+
+## Troubleshooting
+
+### Runner not found
+
+!!! failure "Error Message"
+
+    The runner process could not be started: The subprocess could not be started (spawn safe-ds-runner ENOENT).
+
+!!! success "Solution"
+
+    1. Make sure, you did the third step of the [installation](#installation) guide correctly.
+    2. Find your scripts directory by running the following in a command line.
+        ```sh
+        python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
+        ```
+
+    Then, adjust the setting `safe-ds.runner.command` in Visual Studio Code. Enter the absolute path to the runner
+    executable. Example:
+
+    ```json
+    {
+        "safe-ds.runner.command": "/path/to/venv/bin/safe-ds-runner"
+    }
+    ```
+
+### Wrong runner version
+
+!!! failure "Error Message"
+
+    The installed runner version `0.9.0` is not compatible with this version of the extension.
+
+    The installed version should match these requirements: `>=0.10.0,<0.11.0`. Please update to a matching version.
+
+!!! success "Solution"
+
+    Run `pip install "safe-ds-runner>=0.10.0,<0.11.0"` in a command line to update the runner.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 5734dac8e..2d68be991 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -14,6 +14,7 @@ nav:
     - README.md
   - Getting Started:
     - Installation: getting-started/installation.md
+    - First Program: getting-started/first-program.md
   - Language Reference:
     - pipeline-language/README.md
     - Files: pipeline-language/files.md
diff --git a/docs/pipeline-language/README.md b/docs/pipeline-language/README.md
index 02b222b5a..7ef05c102 100644
--- a/docs/pipeline-language/README.md
+++ b/docs/pipeline-language/README.md
@@ -1,7 +1,6 @@
 # Language Reference
 
-This part of the documentation provides a detailed reference for the Safe-DS DSL. It is divided into the following
-sections:
+This part of the documentation provides a detailed reference for the Safe-DS language. It is divided into the following sections:
 
 -