Apply Steve's review comments on 'installation from packages'

Author: ksuess

docs/glossary.md

@@ -47,7 +47,7 @@ Linode
     [Linode.com](https://www.linode.com/) is an American privately owned virtual private server provider company based in Galloway, New Jersey, United States.
 
 mxdev
-    [mxdev](https://github.com/mxstack/mxdev) [mɪks dɛv] is a utility that makes it easy to work with Python projects containing lots of packages, of which you only want to develop some.
+    [mxdev](https://github.com/mxstack/mxdev) [mɪks dɛv] is a utility that makes it easy to work with Python projects containing lots of packages, and you want to develop only some of those packages.
     It is designed for developers who use stable version constraints, then layer their customizations on top of that base while using a version control system.
     This design allows developers to override their base package constraints with a customized or newer version.
 
@@ -348,7 +348,7 @@ Slate
     It enables you to create powerful, intuitive editors similar to those you've probably used in Medium, Dropbox Paper, or Google Docs.
 
 volto-slate
-    `volto-slate` is an interactive default text editor for Volto, developed on top of {term}`Slate` while offering enhanced WYSIWYG functionality and behavior.
+    `volto-slate` is an interactive default text editor for Volto, developed on top of {term}`Slate`, offering enhanced WYSIWYG functionality and behavior.
 
 elementEditor
     A generic {term}`volto-slate` plugin architecture that can be used to create other editor interactions that follow the pattern of having a button that toggles a format (an inline element).
@@ -358,11 +358,11 @@ WSGI
     The Web Server Gateway Interface (WSGI, pronounced _WIZ-ghee_) is a simple calling convention for web servers to forward requests to web applications or frameworks written in the Python programming language. 
 
 ZEO
-    [ZEO](https://zeo.readthedocs.io/) is a client-server storage for ZODB for sharing a single storage among many clients.
+    [ZEO](https://zeo.readthedocs.io/en/latest) is a client-server storage for ZODB for sharing a single storage among many clients.
 
 ZODB
-    [A native object database for Python](https://zodb.org/).
+    [A native object database for Python](https://zodb.org/en/latest/).
 
 Zope
-    [Zope](https://zope.readthedocs.io/) is a Python-based application server for building secure and highly scalable web applications.
+    [Zope](https://zope.readthedocs.io/en/latest/) is a Python-based application server for building secure and highly scalable web applications.
 ```

docs/install/index.md

@@ -28,7 +28,9 @@ What do you want to do?
 
 ## Choose an installation method
 
-% TODO Explanation when to choose which installation method: container vs installation from its packages. Combination for backend and frontend?
+```{todo}
+Explanation when to choose which installation method: container vs installation from its packages. Combination for backend and frontend?
+```
 
 Developers may choose to install Plone from either [the official container images](containers/index) or [source](source).
 
@@ -69,6 +71,6 @@ System requirements depend upon your choice of installation method:
 :hidden: true
 
 containers/index
-source
-source-step-by-step
+installation-from-packages
+installation-backend-from-packages-step-by-step
 ```

docs/install/source-step-by-step.md …on-backend-from-packages-step-by-step.mddocs/install/source-step-by-step.md renamed to docs/install/installation-backend-from-packages-step-by-step.md docs/install/source-step-by-step.md renamed to docs/install/installation-backend-from-packages-step-by-step.md

@@ -2,39 +2,37 @@
 html_meta:
   "description": "Install Plone 6 backend from its packages for the one who wants to look under the hood"
   "property=og:description": "Install Plone 6 backend from its packages for the one who wants to look under the hood"
-  "property=og:title": "Install Plone backend from its Packages – Step by Step"
+  "property=og:title": "Install Plone backend from its Packages – Step-by-step"
   "keywords": "Plone, Plone 6, install, backend, pip, mxdev, mxmake, cookiecutter, packages, source, Zope, buildout"
 ---
 
 
-(install-source-stepbystep-start-label)=
+(installation-backend-from-packages-step-by-step-start-label)=
 
-# Install Plone backend from its Packages – Step by Step
-
-
-(install-source-stepbystep-backend-start-label)=
-
-## Backend
+# Install Plone backend from its Packages – Step-by-step
 
 For system requirements and pre-requisites for the installation see {ref}`install-source-system-requirements-label`.
 
-We install the Plone backend with `pip`, `cookiecutter-zope-instance`, `mxdev` and other fancy helpers.
+We install the Plone backend with `pip`, `cookiecutter-zope-instance`, `mxdev` and other developer tools.
 
 ```{note}
-There will be one single cookiecutter template to install both backend and frontend from its packages. You will find the instructions on {ref}`install-source-installation-jump-label`. That chapter is for you if you want to develop and want to jump in with all steps prepared by an overall cookiecutter. The subsequent sections explain the installation of the backend step by step. You will learn the details of the installation included in the future overall cookiecutter.
+There will be one single cookiecutter template to install both backend and frontend from its packages.
+You will find the instructions on {ref}`install-source-installation-jump-label`.
+That chapter is for you if you want to develop and want to jump in with all steps prepared by an overall cookiecutter.
+The subsequent sections explain the installation of the backend step-by-step.
+You will learn the details of the installation included in the future overall cookiecutter.
 ```
 
 
-(install-source-installation-steps-label)=
-
-### Installation steps
+(installation-backend-from-packages-installation-steps-label)=
 
-Create a new directory to hold your project, make it your current directory, then issue the following commands in a shell session.
+## Installation steps
 
-Create a Python virtual environment in the current directory.
+Create a new directory to hold your project and make it your current directory.
+Next issue the following commands in a shell session to create a Python virtual environment in the current directory.
 
 ```shell
-python3.9 -m venv venv
+python -m venv venv
 source venv/bin/activate
 ```
 
@@ -49,9 +47,10 @@ pip install -U pip wheel
 The Plone packages and dependencies are installed in trees.
 
 ```
-venv/lib/Python3.x/
-site-packages/
-┌── plone/
+venv/lib/python3.x/site-packages
+│
+…
+├── plone
 │   ├── …
 │   ├── app/
 │       ├── caching/
@@ -69,9 +68,8 @@ Install Plone 6 with constrained requirements using `pip`.
 pip install Plone -c https://dist.plone.org/release/6.0.0a6/constraints.txt
 ```
 
-````{admonition} mkwsgiinstance's minimal Zope configuration
+:::{admonition} <span>`mkwsgiinstance` creates a home with a minimal configuration for a Zope instance.</span>
 :class: margin toggle
-`mkwsgiinstance` creates a home with a minimal configuration for a Zope instance.
 
 ```
 ┌── etc/
@@ -84,11 +82,11 @@ pip install Plone -c https://dist.plone.org/release/6.0.0a6/constraints.txt
     ├── log/
     └── REAMDME.txt/
 ```
-````
+:::
 
-Create a Zope instance with the given username and password in the current directory.
+(installation-backend-from-packages-step-by-step-mkwsgiinstance)=
 
-(install-source-mkwsgiinstance)=
+Create a Zope instance with the given username and password in the current directory.
 
 ```shell
 mkwsgiinstance -u admin:admin -d .
@@ -98,7 +96,7 @@ mkwsgiinstance -u admin:admin -d .
 :class: margin
 
 ```shell
-python3.9 -m venv venv
+python -m venv venv
 source venv/bin/activate
 pip install -U pip wheel
 pip install Plone -c https://dist.plone.org/release/6.0.0a6/constraints.txt
@@ -112,18 +110,18 @@ Start the Zope instance.
 runwsgi ./etc/zope.ini
 ```
 
+It will take a few seconds to start the Zope instance.
 You can stop the instance later with {kbd}`ctrl-esc`.
 
-If you now open the browser with http://localhost:8080/, you see that you already can create a Plone instance.
-Before doing this, we configure our Zope instance for blobs, configure add-ons, etc..
+Before creating a Plone site on http://localhost:8080/, we configure our Zope instance for blobs, configure add-ons, etc..
 
 For the configuration, you have two options:
 1. *manual* configuration by editing {file}`site.zcml` and {file}`zope.conf` (^[Configuring and Running Zope](https://zope.readthedocs.io/en/latest/operation.html))
 2. *generate* configuration by applying `cookiecutter-zope-instance`
 
 (install-source-cookiecutter-zope-instance-label)=
 
-#### Generate Plone / Zope configuration with cookiecutter
+### Generate Plone / Zope configuration with cookiecutter
 
 {term}`Cookiecutter` creates projects from project templates.
 {term}`cookiecutter-zope-instance` is such a template that allows to create a complete Zope configuration. 
@@ -239,7 +237,7 @@ If you want to develop a Plone package, then the subsequent section is for you.
 
 (install-source-checkout-and-pin)=
 
-#### Checkout or version pinning of a Plone package
+### Checkout or version pinning of a Plone package
 
 If you want to checkout a Plone Core package for development or just want to override the constraints of Plone, then a first attempt would be to define constraints with a {file}`constraints.txt` to tell pip to install a different version of a Plone package.
 

docs/install/source.md …cs/install/installation-from-packages.mddocs/install/source.md renamed to docs/install/installation-from-packages.md docs/install/source.md renamed to docs/install/installation-from-packages.md

@@ -49,7 +49,7 @@ Application server {term}`Zope` with its database {term}`ZODB` provides the base
 
 ## Installation backend
 
-We install the Plone backend with {term}`pip`, {term}`mxdev` and other fancy helpers.
+We install the Plone backend with {term}`pip`, {term}`mxdev` and other developer tools.
 
 If you used Plone before, you are probably familiar with a `buildout` Plone installation. 
 The installation with `zc.buildout` was the way to go for Plone 5. 
@@ -78,18 +78,17 @@ Plone 6 prefers to be installed with {term}`pip`, which is the mainstream packag
 
 ```{important}
 There will be one single cookiecutter template to install both backend and frontend.
-By now the chapter {ref}`install-source-stepbystep-start-label` is for you.
+By now the chapter {ref}`installation-backend-from-packages-step-by-step-start-label` is for you.
 It explains the installation of the backend with `pip`.
 ```
 
-<!-- TODO Add installation steps for future cookiecutter template 'cookiecutter-plone-starter' https://github.com/collective/cookiecutter-plone-starter/
+```{todo} Add installation steps for future cookiecutter template 'cookiecutter-plone-starter' https://github.com/collective/cookiecutter-plone-starter/
 
-Create a new directory to hold your project, make it your current directory, then issue the following commands in a shell session.
-
-Create a Python virtual environment in the current directory.
+Create a new directory to hold your project and make it your current directory.
+Issue the following commands in a shell session to create a Python virtual environment in the current directory.
 
 ```shell
-python3.9 -m venv venv
+python -m venv venv
 source venv/bin/activate
 ```
 
@@ -141,14 +140,14 @@ We are now working with `make`. All available commands are listed with
 `make help`.
 
 We could now build and run Zope / Plone with one command `make run`.\
-Instead we customize the setting with additional add-ons and constraints of a Plone package and a checkout of a Plone package. -->
+Instead we customize the setting with additional add-ons and constraints of a Plone package and a checkout of a Plone package. ``-->``
 
 
 (install-source-tweak-backend-installation-label)=
 
 ### Tasks on your backend installation from its packages
 
-You have installed Plone with `pip` like explained above or in {ref}`install-source-stepbystep-start-label`.
+You have installed Plone with `pip` like explained above or in {ref}`installation-backend-from-packages-step-by-step-start-label`.
 
 Add an add-on
 : Add a line with the name of your add-on to `requirements.txt` and add it to {ref}`instance.yaml<install-source-cookiecutter-zope-instance-presets-label>`, then install with pip and apply cookiecutter:
@@ -495,10 +494,11 @@ You have completed the installation of Plone 6 with Volto frontend.
 Welcome to Plone 6!
 
 
-<!-- TODO I have now my local environment with add-ons. How do I deploy? 
+```{todo}
+Now I have my local environment with add-ons. How do I deploy? 
 - instructions, configuration, secrets with Ansible
 - orchestrating processes with pm2 https://pm2.keymetrics.io/ see Volto chapters
--->
+```
 
 
 (install-source-process-manger)=
@@ -569,8 +569,6 @@ pm2 stop plone_backend_tutorial
 % Future cookiecutter template for backend and frontend
 % - {term}`cookiecutter-plone-starter`
 
-<!-- TODO Update used tools -->
-
 
 ## Footnotes