Merge pull request #1749 from plone/choose-ui

Start "Choose a user interface" conceptual guide

Author: davisagli

docs/_static/classic-ui.png

@@ -81,7 +81,7 @@ This is [PLIP 1351](https://github.com/plone/Products.CMFPlone/issues/1351).
 #### For end users
 
 This has no changes for Editors.
-Admins will notice that the ZMI has a new Twitter Bootstrap-based theme, and some control panels have moved.
+Admins will notice that the ZMI has a new Bootstrap-based theme, and some control panels have moved.
 
 
 #### For developers

docs/_static/volto-ui.png

@@ -128,9 +128,9 @@ zodb-temporary-storage = off
 
 (v60-templates-bootstrap-5-label)=
 
-## Changed templates to Twitter Bootstrap 5 markup
+## Changed templates to Bootstrap 5 markup
 
-All templates in core Plone have been updated to use Twitter Bootstrap 5 markup.
+All templates in core Plone have been updated to use Bootstrap 5 markup.
 Add-on authors are encouraged to do the same.
 If you have customized a core template, you should check if your change is still needed, and update it to fit the new markup.
 Any CSS and JavaScript that relies on a specific structure, or certain IDs or classes, should be checked as well.

docs/backend/upgrading/version-specific-migration/upgrade-to-52.md

@@ -23,7 +23,7 @@ Examples include the following.
 
 ## Bootstrap Icons
 
-Twitter Bootstrap 5 is the default CSS framework in Plone 6.
+Bootstrap 5 is the default CSS framework in Plone 6.
 Plone uses its icons.
 Check out all the available Bootstrap icons at [icons.getbootstrap.com](https://icons.getbootstrap.com/).
 

docs/backend/upgrading/version-specific-migration/upgrade-to-60.md

@@ -1,49 +1,22 @@
 ---
 myst:
   html_meta:
-    "description": "Classic UI is a secondary user interface for Plone, but updated to use Twitter Bootstrap 5. It is familiar to users of Plone 5."
-    "property=og:description": "Classic UI is a secondary user interface for Plone, but updated to use Twitter Bootstrap 5. It is familiar to users of Plone 5."
+    "description": "Classic UI is a secondary user interface for Plone, but updated to use Bootstrap 5. It is familiar to users of Plone 5."
+    "property=og:description": "Classic UI is a secondary user interface for Plone, but updated to use Bootstrap 5. It is familiar to users of Plone 5."
     "property=og:title": "Classic UI"
-    "keywords": "Plone 6, Classic UI, Twitter Bootstrap 5"
+    "keywords": "Plone 6, Classic UI, Bootstrap 5"
 ---
 
 (classic-ui-index-label)=
 
 # 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.
+This chapter is a developer reference manual for working with {term}`Classic UI`.
 
-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 their differences, see {doc}`/conceptual-guides/choose-user-interface`.
+```
 
 ```{toctree}
 :maxdepth: 2

docs/classic-ui/icons.md

@@ -47,7 +47,7 @@ Add screenshots.
 
 ## CSS variables
 
-Plone uses Twitter Bootstrap's CSS variables.
+Plone uses Bootstrap's CSS variables.
 They are used to tweak colors, fonts, spacing, and other CSS attributes.
 
 ```{todo}

docs/classic-ui/index.md

@@ -11,8 +11,8 @@ myst:
 
 # What's new in Plone 6 Classic UI
 
--   HTML markup is now based on [Twitter Bootstrap 5](https://getbootstrap.com/).
--   Twitter Bootstrap 5 icons are now included.
+-   HTML markup is now based on [Bootstrap 5](https://getbootstrap.com/).
+-   Bootstrap 5 icons are now included.
 -   Bootstrap JavaScript is available by default.
 -   JavaScript has been modernized.
 -   RequireJS has been removed.

docs/classic-ui/theming/through-the-web.md

@@ -0,0 +1,68 @@
+---
+myst:
+  html_meta:
+    "description": "Explanation of how to choose between Plone's two user interfaces, Volto and Classic UI"
+    "property=og:description": "Explanation of how to choose between Plone's two user interfaces, Volto and Classic UI"
+    "property=og:title": "Choose a user interface"
+    "keywords": "Plone 6, Conceptual guides, UI, user interface, frontend, Volto, Classic UI, distribution"
+---
+
+# Choose a user interface
+
+This guide explains the differences between Plone's two user interfaces, Volto and Classic UI, to help inform you to choose one when developing your new project in Plone, or whether to migrate from Classic UI to Volto.
+There is no migration path available from Volto to Classic UI.
+
+The choice of user interface has implications for editors, admins, and developers.
+
+`````{grid} 1 1 1 2
+:gutter: 1
+:margin: 0
+:padding: 0
+
+````{grid-item-card} Volto
+```{image} /_static/volto-ui.png
+:alt: Plone home page in Volto
+:target: /_static/volto-ui.png
+```
+
+For editors and other end users:
+
+-   The user interface is a fast, modern, single-page web application.
+-   Editors can create sophisticated page layouts by arranging {term}`blocks` of different types.
+-   There is not a comprehensive {doc}`/volto/user-manual/index` yet, and only a few pages exist.
+
+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 {term}`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 home page in Classic UI
+:target: /_static/classic-ui.png
+```
+
+For editors and other end users:
+
+-   The user interface is similar to Plone 5.
+-   Editors create a page using a {term}`WYSIWYG` editor, {term}`TinyMCE`.
+-   Additional widgets can be added to predefined locations, using {term}`portlets`.
+    More sophisticated page layout requires the use of add-ons.
+-   There is a comprehensive [User Manual for Plone 5](https://5.docs.plone.org/working-with-content/index.html), 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`.
+-   The visual design is based on the {term}`Barceloneta` theme from Plone 5, but updated to use Bootstrap 5.
+-   Content is stored as HTML.
+-   Customization of themes is not well-documented.
+
+````
+`````

docs/classic-ui/whatsnew.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

@@ -108,9 +108,9 @@ pm2
     [PM2](https://pm2.keymetrics.io/) is a daemon process manager.
 
 REST API
-    ```{todo}
-    REST API in general. REST API of Plone.
-    ```
+    A REST API (also called a RESTful API or RESTful web API) is an application programming interface (API) that conforms to the design principles of the representational state transfer (REST) architectural style.
+    REST APIs provide a flexible, lightweight way to integrate applications and to connect components in microservices architectures.
+    Plone uses [`plone.restapi`](https://github.com/plone/plone.restapi/) for its REST API.
 
 S3
     [Amazon Web Services S3](https://aws.amazon.com/s3/).
@@ -172,11 +172,11 @@ 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.
+    Elements are the dynamic components of your {term}`blocks`.
     They can be input fields, buttons, or computed HTML.
     They can also return JSON if you call them from a JavaScript app.
 
@@ -422,18 +422,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, or frontends, 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, or frontends, 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.
@@ -447,11 +448,17 @@ Patternslib
     Accessibility, SEO, and well-structured HTML are core values of Patterns.
 
 Slate
-    [Slate.js](https://docs.slatejs.org/) is a highly customizable platform for creating rich-text editors, also known as `WYSIWYG` editors.
+    [Slate.js](https://docs.slatejs.org/) is a highly customizable platform for creating rich-text editors, also known as {term}`WYSIWYG` editors.
     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`, offering enhanced WYSIWYG functionality and behavior.
+    `volto-slate` is an interactive default text editor for Volto, developed on top of {term}`Slate`, offering enhanced {term}`WYSIWYG` functionality and behavior.
+
+WYSIWYG
+    WYSIWYG is an acronym for "what you see is what you get", referring to software that allows content to be edited in a form that resembles its appearance when printed or displayed as a finished product.    
+
+TinyMCE
+    The rich text {term}`WYSIWYG` editor used in {term}`Classic UI`.
 
 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).
@@ -802,4 +809,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 pages 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

@@ -39,8 +39,9 @@ https://demo.plone.org/
 ## Install Plone
 
 First, choose a Plone user interface, or frontend.
-% TODO: once https://github.com/plone/documentation/pull/1749 is merged, link to it
+You can read {doc}`/conceptual-guides/choose-user-interface` to help inform your choice between Volto and Classic UI.
 
+Then choose one of the following installation methods.
 If you are following a [Plone training](https://training.plone.org/), it should specify which option to choose.
 
 {doc}`create-project-cookieplone`