plone · sneridagh · Feb 1, 2022 · Jan 27, 2022 · Jan 27, 2022 · Jan 28, 2022
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -20,12 +20,9 @@ extra_css:
 
 nav:
   - Getting Started:
-      - Bootstrap Volto: 'getting-started/install.md'
+      - Installing Volto: 'getting-started/install.md'
       - Developer roadmap: 'getting-started/roadmap.md'
       - Learning resources: 'getting-started/others.md'
-      - How does it work under the hood: 'getting-started/howdoesitwork.md'
-  - Design principles: 'design-principles/index.md'
-  - Style Guide: 'style-guide/index.md'
   - Configuration:
       - What is configurable?: 'configuration/how-to.md'
       - Settings reference guide: 'configuration/settings-reference.md'
@@ -79,6 +76,8 @@ nav:
       - Performance improvements: 'deploying/performance.md'
   - Upgrade Guide: 'upgrade-guide/index.md'
   - Developer Guidelines:
+      - Design principles: 'developer-guidelines/design-principles.md'
+      - Style Guide: 'developer-guidelines/style-guide.md'
       - Language features: 'developer-guidelines/language-features.md'
       - Linting: 'developer-guidelines/linting.md'
       - React: 'developer-guidelines/react.md'

diff --git a/docs/source/configuration/backend.md b/docs/source/configuration/backend.md
@@ -1,13 +1,13 @@
 # Backend configuration
 
 ## plone.volto
-In order to fully support all Volto features, the Plone backend, needs to be prepared for
-Volto. This involves configuration, add-ons installation and some patches to the core.
-The add'on `plone.volto` does all the heavy lifting for you and it's ready to use
+In order to fully support all Volto features, the Plone backend API needs to be prepared
+for Volto. The add'on `plone.volto` does all the heavy lifting for you and is ready to use
 in your own projects. We used it in our Getting Started section.
 
-However, this package is oppinionated and might not fit your needs, so if you want to
-use your own integration package instead, just take a look at the features it provides,
+This package is slightly opinionated but provides the correct default settings for when
+you want to start with Volto. If you have advanced needs or want to move the setting to
+your own integration package instead, just take a look at the features it provides,
 copy the ones you need for your project and create your own integration package.
 
 https://github.com/plone/plone.volto

diff --git a/docs/source/configuration/how-to.md b/docs/source/configuration/how-to.md
@@ -14,9 +14,10 @@ like:
 const absoluteUrl = `${config.settings.apiPath}/${content.url}`
 ```
 
-Both add-ons and projects can extend Volto's configuration registry. First the add-ons
-configuration is applied, in the order they are defined in `package.json`, then finally
-the project configuration is applied. Visualized like a pipe would be:
+Both the main project and individual add-ons can extend Volto's configuration registry.
+First the add-ons configuration is applied, in the order they are defined in 
+`package.json`, then finally the project configuration is applied. Visualized like
+a pipe would be:
 
 > Default Volto configuration -> Add-on 1 -> Add-on 2 -> ... -> Add-on n -> Project
 

diff --git a/docs/source/configuration/internalproxy.md b/docs/source/configuration/internalproxy.md
@@ -1,28 +1,42 @@
-# Internal proxy to API
+# Internal proxy to content backend API
+
+The server side Volto SSR process (based on Razzle) has an internal proxy to the backend API
+enabled by default.
 
-While in development, Volto has an internal proxy to the backend API enabled by default.
 It provides a better developer experience out of the box, so the developer doesn't has to
 deal with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) and can focus on
 develop/test drive/demo Volto.
 
+To understand the need for the internal proxy, there are three processes running in a Volto website:
+
+1. A frontend web application running in your browser (Javascript)
+2. A Node.js server process that delivers the javascript to the client and does
+   Server Side Generation (SSR) of your pages on first request (Javascript, the
+   Razzle package is used for SSR)
+3. A Plone server process that stores and delivers all content through a REST API (Python)
+
 ## Configuration
 
-By default, Volto expects a Plone backend located at `http://localhost:8080/Plone`.
-These are the settings that allows you to configure the API and how the proxy works:
+The default values from Volto configuration expect a Plone content backend located at `http://localhost:8080/Plone`. Below are the settings that allows you to change the its location
 
-- `apiPath` [API_PATH] - URL of the backend, used through Volto. By default, the proxy URL.
-- `devProxyToApiPath` - The real backend URL, used by the proxy. By default, `http://localhost:8080/Plone`
+- `apiPath` [API_PATH] - URL of the backend, used by Volto running in the frontend browser. By default, the proxy URL. (http://localhost:3000/++api++/)
+- `devProxyToApiPath` - The real backend URL, picked up by the Volto Node.js server process. By default, `http://localhost:8080/Plone`
 
-!!! tip
-    You don't want to deal with CORS in your production deployments, so using the proxy is only meant to be enabled in development mode (e.g `yarn start`). However, for convenience and for testing/demoing using the stock build, it's also enabled in production mode since Volto 14.
 
-!!! note
-    You can disable the proxy by redefining a new `apiPath` and redefining an empty
-    `devProxyToApiPath` setting.
+What happens in the default development configuration/setup:
 
-Here are some examples.
+* The client side Volto javascript files precooked HTML (SSR) is served from http://localhost:3000/ by the NodeJS server process
+* The client javascript does API requests for content and other data on the same url at http://localhost:3000/++api++/
+* The NodeJS service its internal proxy requests the data from the Plone content backend api and delivers
+back json to the frontend.
+* The web browser application is happy, because all connections go through the same URL and no CORS related security issues will be triggered.
 
-### Redefining the proxy target
+!!! tip
+    You could also use the internal proxy for production setups. For convenience and for testing/demoing using the stock build, it is also enabled in production mode since Volto 14. But it is bad for
+    performance because the server side running Node process is also responsable for generating the
+    SSR HTML. With Nginx, Apache or another 'reverse proxy' you can also create an internal API mount which is more suited for that. For more deployment information see ['Seemless mode'](/deploying/seamless-mode)
+
+### Examples redefining the proxy target
 
 You can redefine the local proxy target by using the `RAZZLE_DEV_PROXY_API_PATH` or setting `devProxyToApiPath` in the configuration object (`src/config.js`).
 
@@ -40,6 +54,8 @@ or use the environment variable:
 RAZZLE_DEV_PROXY_API_PATH=http://localhost:8081/mysite yarn start
 ```
 
+This redefines the request path from the server side Node proces to the Plone content backend API, but
+leaves the frontend Volto process making all content requests to http://locahost:3000/
 ### Disabling the proxy
 
 ```js
@@ -55,6 +71,11 @@ or use the environment variable:
 RAZZLE_DEV_PROXY_API_PATH= RAZZLE_API_PATH=http://localhost:8081/mysite yarn start
 ```
 
+If you disable the proxy, the frontend Volto javascript process in the browser will directly query 
+the Plone content backend API. If that URL is on a different domain as from which Volto is
+initially served, you will run into CORS issues if the content backend API doesn't contain the correct
+CORS headers. 
+
 !!! tip
     To view the existing configuration, add console.log(config) to the `applyConfig` function. This dumps the existing config to your terminal console.
 

diff --git a/docs/source/style-guide/Quanta.pdf → docs/source/developer-guidelines/Quanta.pdf b/docs/source/style-guide/Quanta.pdf → docs/source/developer-guidelines/Quanta.pdf
diff --git a/docs/source/design-principles/index.md → ...developer-guidelines/design-principles.md b/docs/source/design-principles/index.md → ...developer-guidelines/design-principles.md
diff --git a/docs/source/style-guide/index.md → ...ource/developer-guidelines/style-guide.md b/docs/source/style-guide/index.md → ...ource/developer-guidelines/style-guide.md
diff --git a/docs/source/getting-started/howdoesitwork.md b/docs/source/getting-started/howdoesitwork.md
diff --git a/docs/source/getting-started/install.md b/docs/source/getting-started/install.md
@@ -5,26 +5,45 @@
 Volto can be installed in any operating system assuming that this requirements
 are met:
 
-- [Node.js LTS (14.x)](https://nodejs.org/)
+- [Node.js LTS (14.x, 16.x)](https://nodejs.org/)
 - [Python 3.7.x / 3.8.x](https://python.org/) or
 - [Docker](https://www.docker.com/get-started) (if using the Plone/Guillotina
   docker images)
 
 Depending on the OS that you are using some of the following might change, they
 are assuming a MacOS/Linux machine:
 
+## Components / Processes running
+
+There are three processes continuously running when you have a working Volto website:
+
+1. A frontend web application running in your browser (Javascript)
+2. A Node.js server process that delivers the javascript to the client and does
+   Server Side Generation (SSR) of your pages on first request (Javascript, the
+   Razzle package is used for SSR)
+3. A Plone server process that stores and delivers all content through a REST API (Python)
+
+When you start with Volto most of the first customisations you will want to make (or mabye
+ever need to make) are in the javascript code used in the browser and Razzle process. Therefore
+this getting started chapter will focus on installing a nodejs/javascript environment locally
+and suggest you start the API backend using a container. 
+
+
 ## Install nvm (NodeJS version manager)
 
-If you have a working nodejs development setup on your machine, this step is
-not required. But it's a good idea to integrate nvm for development, as it
-provides easy access to any Nodejs released version.
+If you have a working Node javascript development already set up on your machine or you prefer
+another management tool to install/maintain node this step is not needed. If you have less 
+experience with setting up javascript, it's a good idea to integrate nvm for development, as
+it provides easy access to any NodeJS released version. 
 
 1. Open a terminal console and type:
 ```bash
 touch ~/.bash_profile
-curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash
+curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.39.1/install.sh | bash
 ```
 
+(Please check the latest available version of nvm on the [main README](https://github.com/nvm-sh/nvm)
+
 2. Close the terminal and open a new one or execute:
 ```
 source ~/.bash_profile
@@ -50,10 +69,8 @@ node -v
     If you're using the fish shell, you can use [nvm.fish](https://github.com/jorgebucaran/nvm.fish)
 
 !!! note
-    Volto supports all currently active NodeJS LTS versions based on [NodeJS
-    Releases page](https://nodejs.org/en/about/releases/). On 2021-04-30 Volto
-    will not support Node 10 as it will reach its end of life.
-
+    Volto supports currently active NodeJS LTS versions based on [NodeJS
+    Releases page](https://nodejs.org/en/about/releases/), starting with Node 12 LTS. 
 ## Yarn (NodeJS package manager)
 
 Install the Yarn Classic version (not the 2.x one!), of the popular node package manager.
@@ -102,7 +119,7 @@ should not throw an error and show the current running containers.
 
 ## Run a Volto ready Plone Docker container
 
-When you have installed Docker, you can run an standard Plone Docker container with the proper configuration for Volto using the `plone.volto` add'on right away by issuing:
+When you have installed Docker, you can use the official Plone Docker container with the proper configuration for Volto using the `plone.volto` add'on right away by issuing:
 
 ```shell
 docker run -it --rm --name=plone \

diff --git a/docs/source/getting-started/others.md b/docs/source/getting-started/others.md
@@ -4,6 +4,15 @@ On the [Plone Trainings Website](https://training.plone.org) you'll find
 Volto-dedicated open training materials plus React and other
 Javascript-centered trainings.
 
+
+## How does it work under the hood
+
+You can watch the talk during the World Plone Day 2021:
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/kHec4MXH8vo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+
+
 ## PloneConf 2019
 
 PloneConf 2019 had several Volto-relevant presentations.