simplify install instructions

1 files changed, 36 insertions, 61 deletions

diff --git a/docs/src/content/overview-installation.md b/docs/src/content/overview-installation.md
index 4b300d72..5b94adfc 100644
--- a/docs/src/content/overview-installation.md
+++ b/docs/src/content/overview-installation.md
@@ -19,14 +19,12 @@ The recommended way to install mitmproxy on macOS is to use
 brew install mitmproxy
 {{< / highlight >}}
 
-Alternatively you can download the binary-packages from our
-[releases](https://github.com/mitmproxy/mitmproxy/releases/latest) page.
+Alternatively, you can download standalone binaries on [mitmproxy.org](https://mitmproxy.org/).
 
 ## Linux
 
 The recommended way to install mitmproxy on Linux is to download the
-binary-packages from our
-[releases](https://github.com/mitmproxy/mitmproxy/releases/latest) page.
+standalone binaries on [mitmproxy.org](https://mitmproxy.org/).
 
 Some Linux distributions provide community-supported mitmproxy packages through
 their native package repositories (e.g., Arch Linux, Debian, Ubuntu, Kali Linux,
@@ -37,15 +35,14 @@ the repository maintainers directly for issues with native packages.
 ## Windows
 
 
-All the mitmproxy tools are fully supported under [WSL (Windows Subsystem for
-Linux)](https://docs.microsoft.com/en-us/windows/wsl/about). We recommend to [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and then
+All the mitmproxy tools are fully supported under 
+[WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/about). 
+We recommend to [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and then
 follow the mitmproxy installation instructions for Linux.
 
 We also distribute native Windows packages for all tools other than the
 mitmproxy console app, which only works under WSL. To install mitmproxy on Windows,
-download the binary packages from our
-[releases](https://github.com/mitmproxy/mitmproxy/releases/latest) page. 
-
+download the installer from [mitmproxy.org](https://mitmproxy.org/).
 After installation, you'll find shortcuts for mitmweb and mitmdump in the start
 menu. Both executables are added to your PATH and can be invoked from the
 command line.
@@ -53,68 +50,46 @@ command line.
 
 # Advanced Installation
 
-## Self-contained Pre-built Binary Packages
-
-For some platforms we provide pre-built binary packages containing ready-to-run
-executables. This includes a self-contained Python 3 environment, a recent
-OpenSSL that support ALPN and HTTP/2, and other dependencies that would
-otherwise be cumbersome to compile and install.
-
-Dependencies in the binary packages are frozen on release, and can't be updated
-in situ. This means that we necessarily capture any bugs or security issues that
-may be present. We don't generally release new binary packages simply to update
-dependencies (though we may do so if we become aware of a really serious issue).
-If you use our binary packages, please make sure you update regularly to ensure
-that everything remains current.
-
-
-## Docker Images
-
-You can use the official mitmproxy images from
-[DockerHub](https://hub.docker.com/r/mitmproxy/mitmproxy/). The same
-security considerations apply as for our binary packages.
+## Development Setup
 
-## Installation on Linux via pip3
+If you would like to install mitmproxy directly from source code or the
+GitHub master branch, please see the our
+[README](https://github.com/mitmproxy/mitmproxy#installation)
+on GitHub.
 
-Please make sure to install Python 3.6 (or higher) and pip3 for your
-distribution. If your distribution does not provide a suitable Python
-version, you can use [pyenv](https://github.com/yyuu/pyenv) to get a
-recent Python environment.
 
-{{< highlight bash  >}}
-sudo apt install python3-pip # Debian 10 or higher, Ubuntu 17.10 or higher
-sudo dnf install python3-pip # Fedora 26 or higher
-sudo pacman -S python-pip # Arch Linux
-{{< / highlight >}}
+## Installation from the Python Package Index (PyPI)
 
-Please make sure to upgrade pip3 itself:
+If your mitmproxy addons require the installation of additional Python packages,
+you can install mitmproxy from [PyPI](https://pypi.org/project/mitmproxy/).
 
-{{< highlight bash  >}}
-sudo pip3 install -U pip
-{{< / highlight >}}
+While there are plenty of options around[^1], we recommend the installation using pipx:
 
-Now you can install mitmproxy via pip3:
+[^1]: If you are familiar with the Python ecosystem, you may know that there are a million ways to install Python 
+    packages. Most of them (pip, virtualenv, pipenv, etc.) should just work, but we don't have the capacity to 
+    provide support for it.
+    
+1. Install a recent version of Python (we require at least 3.6).
+2. Install [pipx](https://pipxproject.github.io/pipx/).
+3. `pipx install mitmproxy`
 
-{{< highlight bash  >}}
-sudo pip3 install mitmproxy
-{{< / highlight >}}
+To install additional Python packages, run `pipx inject mitmproxy <your-package-name>`.
 
-## Installation on Windows via pip3
+## Docker Images
 
-First, install the latest version of Python 3.6 or higher from the
-[Python website](https://www.python.org/downloads/windows/). During
-installation, make sure to select Add Python to PATH. There are no other
-dependencies on Windows.
+You can use the official mitmproxy images from
+[DockerHub](https://hub.docker.com/r/mitmproxy/mitmproxy/).
 
-Now you can install mitmproxy via pip3:
+## Security Considerations for Binary Packages
 
-{{< highlight bash  >}}
-pip3 install mitmproxy
-{{< / highlight >}}
+Our pre-compiled binary packages and Docker images include a self-contained Python 3 environment,  a recent version of 
+OpenSSL that support ALPN and HTTP/2, and other dependencies that would otherwise be cumbersome to compile and install.
 
-## Installation from Source
+Dependencies in the binary packages are frozen on release, and can't be updated
+in situ. This means that we necessarily capture any bugs or security issues that
+may be present. We don't generally release new binary packages simply to update
+dependencies (though we may do so if we become aware of a really serious issue).
+If you use our binary packages, please make sure you update regularly to ensure
+that everything remains current.
 
-If you would like to install mitmproxy directly from source code or the
-GitHub master branch, please see the our
-[README](https://github.com/mitmproxy/mitmproxy/blob/master/README.rst)
-on GitHub.
+As a general principle, mitmproxy does not "phone home" and consequently will not do any update checks.
\ No newline at end of file