diff --git a/docs/installation_instructions.md b/docs/installation_instructions.md
index ad6de89fb8844232cee5f6aa257da107be7e2643..c675bb8b868181264055f097bef02a945e5a7453 100644
--- a/docs/installation_instructions.md
+++ b/docs/installation_instructions.md
@@ -1,7 +1,13 @@
 # OpenAppStack installation instructions
 
-This document describes how you can set up a single-node OpenAppStack cluster.
-Support for multi-node clusters will come in the future.
+This document describes how you can install OpenAppStack on a VPS. The
+installation process wil set up a "Kubernetes cluster" which runs several open
+source applications. More information about the applications can be found on the
+[OpenAppStack website](https://openappstack.net/).
+
+This document describes how you can set up a "single-node" OpenAppStack cluster.
+This means everything runs on the same VPS.  Support for "multi-node" clusters
+(a Kubernetes cluster on more than one VPS) will come in the future.
 
 > **NOTE:** All commands in these installation instructions need to be run on a
 > trusted provisioning machine (i.e., your laptop) that is *not* the VPS that
@@ -25,7 +31,8 @@ guide][https://openappstack.net/contact.html).
 
 ## Prerequisites
 
-* A virtual machine or bare metal server with:
+* During these instructions, you are asked to make a VPS, or have a bare metal
+  server ready. The server should meet these requirements:
   * Current Debian stable "buster"
   * A public IP address
   * The ability to create DNS records for this IP
@@ -35,14 +42,16 @@ guide][https://openappstack.net/contact.html).
   * Root ssh access
   * Python3 installed
 
-* A trusted local machine to run the installer on (we call this the `provisioning
-  machine`):
+* A trusted machine to run the installer on (we call this the `provisioning
+  machine`). All the commands listed in these instructions should be run on the
+  provisioning machine, unless specified otherwise.
   * You need Python 3 and Git installed (`apt install python3 git`)
   * We recommend using a [python virtualenv](https://docs.python.org/3/tutorial/venv.html)
     to make sure we do not change any of your other projects. Install virtualenv
     by running `pip3 install --user venv` or `apt install python3-venv`
+  * `ssh-agent` to give you access to your VPS
 
-## Install OpenAppStack command line tool
+## Install OpenAppStack CLI on your provisioning machine
 
 On your **provisioning machine**, clone the OpenAppStack git repository and
 checkout the latest tagged version (currently `0.3.0`):
@@ -82,7 +91,7 @@ it out by running
 
     $ python -m openappstack my-cluster --help
 
-## Install OpenAppStack
+## Install OpenAppStack on your VPS
 
 Setting up OpenAppStack on your VPS happens in three steps:
 
@@ -109,12 +118,16 @@ information about the `create` subcommand:
 
     $ python -m openappstack my-cluster create --help
 
-There are two options to create a cluster:
+There are two options to create a cluster, [using the Greenhost
+API](#option-1--setup-with-the-greenhost-api) or [using any other
+machine](#option-2--setup-any-vps-or-bare-metal-server). Choose one of these
+options, and skip to the "[Installation](#installation)" subchapter afterwards.
 
-#### Using the Greenhost API
+#### OPTION 1: Setup with the Greenhost API
 
-- For this to work, you need to have an API key with Customer rights.
-  1. In the Cosmos service centre, click your name on the top right corner
+- Before you can start, you need to have an API key with Customer rights.
+  1. In the Cosmos service centre, click your webmaster account name on the top
+     right corner
   2. Go to "User settings"
   3. Click "API keys"
   4. Click "New API key"
@@ -178,11 +191,15 @@ There are two options to create a cluster:
   - An `A` record `oas.example.org` pointing to the VPSs IP address
   - A `CNAME` record `*.oas.example.org` pointing to `oas.example.org`.
 
-#### Using any VPS or bare metal server
+#### OPTION 2: Setup any VPS or bare metal server
+
+Skip this step and continue to [Installation](#installation) if you already set
+up a Greenhost VPS.
 
-If you want to follow this step, we assume you already have a machine with a
-world-facing IP address. You'll need its *hostname* and its *IP address*. Also
-check that your VPS meets our [prerequisites](#prerequisites).
+If you want to install OpenAppStack on a non-Greenhost VPS, we assume you
+already have a machine with a world-facing IP address. Make sure that your VPS
+meets our [prerequisites](#prerequisites).  You'll need its *hostname* and its
+*IP address*.
 
 > **NOTE:** You can use the `--acme-staging` argument for testing purposes. If
 > you are automating this, please use this to ensure you use "staging"
@@ -194,7 +211,7 @@ If you want your cluster to be reachable under the fully qualified domain name
 (`FQDN`) `oas.example.org`, the corresponding parameters would be:
 
 * `--subdomain`: `oas`
-* your `DOMAIN`: `example.org`
+* the `DOMAIN` positional argument: `example.org`
 
 Create the OpenAppStack settings for your VPS by running the following command:
 
@@ -202,7 +219,7 @@ Create the OpenAppStack settings for your VPS by running the following command:
 $ python -m openappstack my-cluster create --ip-address IP_ADDRESS --subdomain oas example.org --create-hostname my-clusters-hostname
 ```
 
-### DNS entries
+##### DNS entries
 
 Before you continue, if you have not made DNS entries with the CLI tool, you
 need to make them now. It is important to start with configuring DNS because
@@ -230,15 +247,13 @@ testing you can skip this step. Please be aware of the limitations of this:
 
 ### Installation
 
-Before you start the installation, make sure your DNS is propagated. To do so,
-make sure 'ping' shows your VPS's IP address:
+You're almost ready to start the OpenAppStack installation script.  First, make
+sure your DNS is propagated. To do so, make sure 'ping' shows your VPS's IP
+address:
 
     $ ping oas.example.org
 
-The installation process sets up a single-node Kubernetes cluster on the machine
-and installs the utility tools [helm](https://helm.sh/),
-[kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) and
-[rke](https://rancher.com/docs/rke/latest/en/). The `install` command will try
+The `install` command will try
 to log into your machine as root using SSH.
 
 To start the installation process, run:
@@ -256,14 +271,32 @@ installation process has compleded, Flux has not necessarily finished installing
 and integrating all the applications. This process can take up to a few hours to
 complete.
 
-You can re-run the `install` command. Make sure you re-run it on a machine with
-the same `secrets` as generated the first time. You can achieve this by making
-sure you have the `clusters/my-cluster` directory and it contains the same
-`secrets` directory before you run the installation command.
+In the future, we will add commands that show you the status of the application
+installation. For now, just wait half an hour for everything to settle, and then
+continue to the Usage section.
+
+> **NOTE:** It is possible to re-run the `install` command. Make sure you re-run
+> it on a machine with the same `secrets` as generated the first time. You can
+> achieve this by making sure you have the `clusters/my-cluster` directory and
+> it contains the same `secrets` directory before you run the installation
+> command.
 
 ## Usage
 
-When the installation is completed, you will have access to these applications:
+After all the applications are installed, the first thing to do is log into
+admin.oas.example.org. Here you can find the "user panel", a place where you can
+create, edit and delete users. You can log in with the user "admin". The
+password can be found in
+`clusters/my-cluster/secrets/userbackend_admin_password`. After logging in, you
+will see an overview of all the applications your user has access to. For more
+information, take a look at the [user panel
+documentation](https://docs.openappstack.net/projects/user-panel/en/latest/).
+
+> **NOTE:** at the moment none of the applications are available at
+> `oas.example.org`, we only provide applications in subdomains. In the future
+> this might change.
+
+These applications should be available after the installation is completed:
 
 * [OAS User panel](https://open.greenhost.net/openappstack/user-panel/), our
   user panel can be used to create and edit users. These users can be used to
@@ -330,10 +363,8 @@ Look for these lines:
 
     export KUBECONFIG=/home/you/projects/openappstack/clusters/my-cluster/secrets/kube_config_cluster.yml
 
-Copy the whole `export` line into your terminal. In *that* terminal, kubectl
-will connect to your cluster.
-
-> **NOTE:** you have to repeat this step in new terminals and terminal tabs.
+Copy the whole `export` line into your terminal. In *the same terminal window*,
+kubectl will connect to your cluster.
 
 ### SSH access
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 7621d3f7724b7895b6fb7f2aedf08ffa6e522067..8c5056e1cd423b16bd63bfb6885ad206892a6c21 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,6 +1,15 @@
 # Troubleshooting
 
-Note: `cluster$` indicates that the commands should be run as root on your OAS cluster.
+If you run into problems, there are a few things you can do to research the
+problem. This document describes what you can do.
+
+> **NOTE:** `cluster$` indicates that the commands should be run as root on your
+> OAS machine.
+
+## Known issues
+
+Take a look if the problem you have encountered is already in our [issue
+tracker](https://open.greenhost.net/groups/openappstack/-/issues).
 
 ## Run the cli tests