Improve install docs (#1760)

* rm deployment from admin guide description, as deployment has it's own chapter

* correct venv creation, never mix venv and other configation files

* Update docs/admin-guide/run-plone.md

Co-authored-by: David Glick <david@glicksoftware.com>

* Apply suggestions from code review

---------

Co-authored-by: David Glick <david@glicksoftware.com>
Co-authored-by: Steve Piercy <web@stevepiercy.com>

Author: 3 people

docs/admin-guide/index.md

@@ -11,7 +11,7 @@ myst:
 
 # Admin guide
 
-In this part of the documentation, you can find how to install, operate, configure, and deploy Plone.
+In this part of the documentation, you can find how to install, operate, and configure Plone.
 
 
 ```{toctree}

docs/admin-guide/install-buildout.md

@@ -25,7 +25,7 @@ For other installation options, see {ref}`get-started-install-label`.
 ## Prerequisites for installation
 
 -   For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60}
-% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest". 
+% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest".
 % -   For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61}
 
 
@@ -47,15 +47,17 @@ cd <my_projects>/plone
 Create a Python virtual environment.
 
 ```shell
-python3 -m venv .
+python3 -m venv venv
 ```
 
 Install the minimal Python packages needed in order to run Buildout.
 
 ```shell
-bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt
+venv/bin/pip install -r https://dist.plone.org/release/6-latest/requirements.txt
 ```
 
+
+
 Create a {file}`buildout.cfg` file in your directory with the following contents.
 
 ```cfg
@@ -75,6 +77,12 @@ eggs =
     Plone
 ```
 
+Use Buildout's [`bootstrap` command](https://www.buildout.org/en/latest/topics/bootstrapping.html) to install a local `buildout` script in the {file}`bin` directory.
+
+```shell
+venv/bin/buildout bootstrap
+```
+
 Run Buildout.
 
 ```shell
@@ -83,6 +91,7 @@ bin/buildout
 
 This may take a few minutes.
 
+Whenever you change the Buildout configuration, run `./bin/buildout` again.
 
 ## Start Plone in foreground mode
 

docs/admin-guide/install-pip.md

@@ -25,7 +25,7 @@ For other installation options, see {ref}`get-started-install-label`.
 ## Prerequisites for installation
 
 -   For Plone 6.0, Python {SUPPORTED_PYTHON_VERSIONS_PLONE60}
-% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest". 
+% TODO: These instructions install Plone 6.0.x. Uncomment next line and change the subsequent include when Plone 6.1 is released and "latest".
 % -   For Plone 6.1, Python {SUPPORTED_PYTHON_VERSIONS_PLONE61}
 
 
@@ -47,13 +47,13 @@ cd <my_projects>/plone
 Create a Python virtual environment.
 
 ```shell
-python3 -m venv .
+python3 -m venv venv
 ```
 
 Install Plone and a helper package, {term}`pipx`.
 
 ```shell
-bin/pip install -c https://dist.plone.org/release/6.0-latest/constraints.txt Plone pipx
+venv/bin/pip install -c https://dist.plone.org/release/6.0-latest/constraints.txt Plone pipx
 ```
 
 

docs/admin-guide/run-plone.md

@@ -19,6 +19,7 @@ There are different commands to run Plone, depending on which method you used to
 
 Running Plone in foreground mode will show output in the terminal.
 This is recommended while developing a Plone site.
+The command you use depends on the installation method you used.
 
 Cookieplone:
 :   ```shell