start choose-user-interface chapter

Author: davisagli

docs/_static/classic-ui.png

@@ -11,40 +11,12 @@ myst:
 
 # Classic UI
 
-```{todo}
-Perhaps some of this introduction should be an include, so we don't have to repeat ourselves?
-```
-
-Plone 6 ships with two user interfaces or frontends.
-
-The default frontend of Plone 6 is Volto.
-It is based on the React JavaScript framework.
-
-The other frontend is based on Twitter Bootstrap 5.
-This frontend is now called {term}`Classic UI`.
-
-
-## Which frontend?
-
-Choosing one frontend over another depends on several factors.
-
-Classic UI would be a better choice for the following situations.
-
--   Reason 1
--   Reason 2
--   Reason N
-
-The default frontend Volto would be a better choice for the following situations.
-
--   Reason 1
--   Reason 2
--   Reason N
-
-
-## Contents
-
 This chapter is a developer reference manual for working with Classic UI.
 
+```{seealso}
+Plone has two user interfaces, Volto and Classic UI. To understand the difference, see {doc}`/conceptual-guides/choose-user-interface`.
+```
+
 ```{toctree}
 :maxdepth: 2
 

docs/_static/volto-ui.png

@@ -0,0 +1,61 @@
+---
+myst:
+  html_meta:
+    "description": "Explanation of how to choose between Plone's user interfaces, Volto and Classic UI"
+    "property=og:description": "Explanation of how to choose between Plone's user interfaces, Volto and Classic UI"
+    "property=og:title": "Choose a user interface"
+    "keywords": "Plone 6, Conceptual guides, UI, frontend, Volto, Classic UI, distribution"
+---
+
+# Choose a user interface
+
+Plone 6 offers two different user interfaces: Volto and Classic UI.
+
+The choice of user interface has implications for editors, admins, and developers.
+
+::::{grid} 2
+:::{grid-item-card}  Volto
+
+```{image} /_static/volto-ui.png
+:alt: Plone homepage in Volto
+```
+
+For editors and other end users:
+
+* The user interface is a fast, modern single-page web application.
+* Editors create a page by arranging blocks of different types into a layout.
+* There is not a comprehensive User Manual yet.
+
+For developers and integrators:
+
+* The frontend is a {term}`React`-based application written in JavaScript and TypeScript.
+* The backend is a Python process which provides a REST API for the frontend.
+* Python skills are not required, but can be helpful for extending the backend.
+* Content is stored as structured JSON.
+* Customization of themes is well-documented and relatively easy for developers who have experience with React.
+
+
+:::
+:::{grid-item-card}  Classic UI
+
+```{image} /_static/classic-ui.png
+:alt: Plone homepage in Classic UI
+```
+
+For editors and other end users:
+
+* The user interface is similar to Plone 5.
+* Editors create a page using a WYSIWYG editor (TinyMCE).
+* Additional widgets can be added to predefined locations, using {term}`portlets`.
+* There is a comprehensive User Manual for Plone 5, but it has not been updated for Plone 6.
+
+For developers and integrators:
+
+* The frontend and backend run in a single Python process, so hosting is a bit simpler.
+* The frontend is implemented as server-side templates using the {term}`ZPT` language.
+* Interactive functionality is implemented in JavaScript using {term}`Mockup`.
+* Content is stored as HTML.
+* Customization of themes is not well-documented.
+
+:::
+::::

docs/classic-ui/index.md

@@ -15,6 +15,7 @@ This part of the documentation provides explanation of concepts to deepen and br
 ```{toctree}
 :maxdepth: 2
 
+choose-user-interface
 package-management
 make-build-backend-walk-through
 ```

docs/conceptual-guides/choose-user-interface.md

@@ -168,8 +168,8 @@ Rapido application
     It contains the features you implement.
     It is a folder containing templates, Python code, and YAML files.
 
-block
-    Blocks display a chunk of HTML which can be inserted in your Plone pages.
+blocks
+    Blocks are the fundamental components of a page layout in {term}`Volto`.
 
 element
     Elements are the dynamic components of your blocks.
@@ -411,18 +411,19 @@ Traefik Proxy
 
 Volto
     [Volto](https://github.com/plone/volto) is a React-based frontend for Plone.
-    It is the default user interface for Plone 6.
+    It is one of two supported user interfaces for Plone 6.
 
-    The other frontend is {term}`Classic UI`.
+    ````{seealso}
+    {doc}`/conceptual-guides/choose-user-interface`
+    ````
 
 Classic UI
-    Classic UI is a secondary frontend for Plone 6.
-    It is integrated with [Products.CMFPlone](https://github.com/plone/Products.CMFPlone/).
-    Its theme is named [Barceloneta](https://github.com/plone/plonetheme.barceloneta/).
-    It is based on Twitter Bootstrap 5.
-    It uses {term}`Mockup` as its JavaScript stack.
+    Classic UI is a frontend for Plone 6 that is based on {term}`ZPT` and {term}`Mockup`.
+    It is one of two supported user interfaces for Plone 6.
 
-    The other frontend is {term}`Volto`.
+    ````{seealso}
+    {doc}`/conceptual-guides/choose-user-interface`
+    ````
 
 Mockup
     [Mockup](https://github.com/plone/mockup/) is a package that, together with {term}`Patternslib`, builds the UI toolkit for {term}`Classic UI`, a frontend for Plone.
@@ -792,4 +793,8 @@ lazy loaded
 reference implementation
     A reference implementation is a program that implements all requirements from a corresponding specification.
     The reference implementation often accompanies a technical standard, and demonstrates what should be considered the "correct" behavior of any other implementation of it.
+
+portlets
+    Portlets are widgets that can be inserted in predefined locations in {term}`Classic UI`.
+    Portlets are most commonly used to add sidebars to the left or right of the main page content.
 ```

docs/conceptual-guides/index.md

@@ -19,7 +19,9 @@ You can also {ref}`try a Plone demo <install-index-try-plone-label>`.
 
 ## Get started
 
-Choose an option to get started with Plone.
+First, read {doc}`/conceptual-guides/choose-user-interface` to choose between Volto and Classic UI.
+
+Then, choose one of the following install methods.
 If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose.
 
 {doc}`create-project`