docs: tweak fin's CI instructions

docs/_index.md

@@ -28,7 +28,7 @@ If you are viewing documentation for the development branch, you may wish to ins
 See the **advanced** installation instructions to use a preview or alternate version of Poetry.
 {{% /note %}}
 
-{{< tabs tabTotal="4" tabID1="installing-with-the-official-installer" tabID2="installing-with-pipx" tabID3="installing-manually" tabID4="ci-recommendation" tabName1="With the official installer" tabName2="With pipx" tabName3="Manually (advanced)" tabName4="CI recommendations">}}
+{{< tabs tabTotal="4" tabID1="installing-with-the-official-installer" tabID2="installing-with-pipx" tabID3="installing-manually" tabID4="ci-recommendations" tabName1="With the official installer" tabName2="With pipx" tabName3="Manually (advanced)" tabName4="CI recommendations">}}
 
 {{< tab tabID="installing-with-the-official-installer" >}}
 
@@ -275,49 +275,76 @@ Poetry will be available at `$VENV_PATH/bin/poetry` and can be invoked directly
 To uninstall Poetry, simply delete the entire `$VENV_PATH` directory.
 
 {{< /tab >}}
-{{< tab tabID="ci-recommendation" >}}
-In contrast to development environments, where always having the latest version of an application is a good idea,
-CI environments should be as much reproducable as possible. Here are some recommendations, when installing Poetry in
-such an environment.
+{{< tab tabID="ci-recommendations" >}}
+Unlike development environments, where making use of the latest tools is desirable, in a CI environment reproducibility
+should be made the priority. Here are some suggestions for installing Poetry in such an environment.
 
-**Pin Poetry version**
+**Installation method**
 
-To ensure reproducable behavior it is highly recommended to explicit set a version during the installation. This can
-be done by either using the `--version` option or set the `$POETRY_VERSION` environment variable:
+The official installer script ([install.python-poetry.org](https://install.python-poetry.org)) offers a streamlined and
+simplified installation of Poetry, sufficient for developer use or for simple pipelines. However, in a CI environment
+the other two supported installation methods (pipx and manual) should be seriously considered.
 
-```bash
-curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0
-curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 -
-```
+**Using install.python-poetry.org**
 
-**Installation method**
+Downloading a copy of the installer script to a place accessible by your CI pipelines (or maintaining a copy of the
+[repository](https://github.com/python-poetry/install.python-poetry.org)) is strongly suggested, to ensure your
+pipeline's stability and to maintain control over what code is executed.
 
-Downloading the installer script from https://install.python-poetry.org always returns the latest version of the script.
-To ensure reproducable behavior of the installation process, other ways are recommended:
+By default the installer will install to a user-specific directory. In more complex pipelines that may make accessing
+Poetry difficult (especially in cases like multi-stage container builds). It is highly suggested to make use of
+`$POETRY_HOME` when using the official installer in CI, as that way the exact paths can be controlled.
 
-***Store a local copy of the installer***
+```bash
+export POETRY_HOME=/opt/poetry
+python3 install-poetry.py --version 1.2.0
+$POETRY_HOME/bin/poetry --version
+```
 
-Either fork the [repository of the installer](https://github.com/python-poetry/install.python-poetry.org) or download
-the installer script once and place it somewhere, where all your CI pipelines have access to. Thus, you have the complete
-control over which version of the installer is used.
+**Using pipx**
 
-***Use pip***
+Just as `pipx` is a powerful tool for development use, it is equally useful in a CI environment. It takes the same steps
+the installer does to safely install Poetry isolated from the rest of your system, but is generic and able to do this
+for any Python package, with a syntax/usage that is similar to `pip`. `pipx` should be considered equally supported in
+comparison to the official installer, and should be one of your top choices for use of Poetry in CI.
 
-The recommended way is using the installer or pipx. Both ensure that Poetry is isolated from other Python packages and
-a global `poetry` command is provided.
+```
+pipx install poetry==1.2.0
+```
 
-However, in a CI environment you have usually a complete control over what is installed and which commands run. Thus, it
-might be suitable to install Poetry via `pip`:
+**Using pip (aka manually)**
 
-```bash
-pip install poetry==1.2.0
+For maximum control in your CI environment, installation with `pip` is fully supported and something you should
+consider. While this requires more explicit commands and knowledge of Python packaging from you, it in return offers the
+best debugging experience, and leaves you subject to the fewest external tools.
+
+```
+virtualenv /opt/poetry
+/opt/poetry/bin/pip install poetry==1.2.0
+/opt/poetry/bin/poetry --version
 ```
 
 {{% note %}}
-If you install Poetry via `pip`, ensure it is not installed in the same environment Poetry should manage. Otherwise it is
-possible that Poetry will accidentally upgrade or uninstall its own dependencies.
+If you install Poetry via `pip`, ensure you have Poetry installed into an isolated environment that is **not the same**
+as the target environment managed by Poetry. If Poetry and your project are installed into the same environment, Poetry
+is likely to upgrade or uninstall its own dependencies (causing hard-to-debug and understand errors).
 {{% /note %}}
 
+**Version pinning**
+
+Whatever method you use, it is highly recommended to explicitly control the version of Poetry used, so that you are able
+to upgrade after performing your own validation. Each install method has a different syntax for setting the version --
+the following are some simple examples:
+
+```bash
+curl -sSL https://install.python-poetry.org | python3 - --version 1.2.0
+# or
+curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 python3 -
+
+pipx install poetry==1.2.0
+
+/path/to/venv/bin/pip install poetry==1.2.0
+```
 {{< /tab >}}
 {{< /tabs >}}