Help installers choose a frontend

[stevepiercy]

Description

We need to give direction to users for what frontend to choose in the Plone 6 Documentation.

We laid out a skeleton in Overview for a comprehensive description of features. That would be one place for it.

Another good spot to make a decision between frontends would be in Install. But it would need some careful thought, not just a copy-pasta, because we already present two decisions already, "demo or install?" and "which install method?". I would be OK to move the demo stuff above the "demo or install" decision tree to make it less complicated. I have to try out a few layouts. Edit: suggestion retracted.

See plone/plone.volto#94 (comment)

Todo

• Create a new Diataxis Explanation page entitled "Choose a user interface"
  • At explanation/choose-user-interface.md.
  • Pull content from overview/index.md and replace it with a link to this new resource.
  • Classic UI uses Portlets. Volto uses blocks.
  • Use the outline from this comment.
• Link to this new page from the entry pages of:
  • classic-ui/index.md
  • volto/index.md (symlinked from submodules/docs/src/index.md)
  • install/index.md
• Add or update terms in the Glossary.
  • frontend
  • user interface
  • backend
  • portlet
  • block
  • Barceloneta
  • Classic-UI
  • Volto
• Review the Installers' UIs for potential revisions.

[fredvd]

I’d like to pick up this one. My analysis is that we still lack a good glossary with not only explantions but a consistent and clear ‘name list’.

while assisting with the Volto installation docs last year I used the term ‘content backend’ or content api when explaining which processes are running where and what you need to setup. That makes sense in the Volto stack because you have two backends. But it is yet another name for the same plone core/backend.

It might be a bit late or too late to rename Classic at this moment. Ok it doesn’t associate with a frontendish idea, but classic does I think refer enough to the frontend we always had in 1.x to 5.2.

Maybe it is enough to have a very clear succinct description of the possible configurations up front in the docs, the overview indeed and refer back to it
from following chapters as you suggest. Also some graphics/model drawings will help for the visual learners.

I find the current installation chapter a bit confusing as well when I read it for the first time. There are 3 or 4 pages you need to link-follow, there is some overlap between those pages and we could improve the wording imho.

So how should we call the plone backend. Plone Core. With builtin html based frontend. Html backed frontend.

If you want to use the new react based frontend you need to load Plone Core with a different setup profile (provided by plone.volto) and run the separate plone-frontend process/confainer.

Maybe we should rename the plone-frontend image to plone-react-frontend. Yes it is technology but it provides the right associations.

First ideas this, just brainstorming on my own here. :-)

[stevepiercy]

Let's focus on the title of the issue, specifically how to choose a frontend, and create new issues as needed.

we still lack a good glossary with not only explantions but a consistent and clear ‘name list’.

We should add a few missing Glossary terms:

• frontend
• backend

We have existing Glossary terms, which might need an update:

• https://6.dev-docs.plone.org/glossary.html#term-Barceloneta
• https://6.dev-docs.plone.org/glossary.html#term-Classic-UI
• https://6.dev-docs.plone.org/glossary.html#term-Volto

What other terms should we add? I think that package and image names are critically important.

But it is yet another name for the same plone core/backend.

Not everything needs a name (or brand or identity), other than its package name. Avoid obfuscation.

It might be a bit late or too late to rename Classic at this moment.

Yes, that was not a good name choice, and we should have learned from Coca-Cola's branding blunder during the 1980's with "new" and "classic". We are stuck with it now. However, let's use "Classic UI" in writing to give it obvious meaning as a user interface. We can continue to be lazy when speaking.

Also some graphics/model drawings will help for the visual learners.

For example, see #1281.

We also have a draft PR that uses graphviz. Example and configuration.

There are 3 or 4 pages you need to link-follow, there is some overlap between those pages and we could improve the wording imho.

Agreed. I suggested to merge Volto's installation docs into the main docs repository. See discussion in plone/plone.volto#94 (comment).

So how should we call the plone backend. Plone Core. With builtin html based frontend. Html backed frontend.

"backend" is good enough for me, provided we have a definition of it in the Glossary.

If you want to use the new react based frontend you need to load Plone Core with a different setup profile (provided by plone.volto) and run the separate plone-frontend process/confainer.

Yes. This is not well-documented and needs to be added, hence this issue (and several others).

Maybe we should rename the plone-frontend image to plone-react-frontend. Yes it is technology but it provides the right associations.

Personally I think that we totally messed up by dropping the well-known "Volto" name, given that we have two concurrent frontends in Plone 5.2 and 6.0. Instead of looking where we were walking, we were staring far into the future when there would be no more Classic UI and only Volto for the frontend. Eventually the name will be correct when Classic UI gets dropped (Plone 7?), so I don't have a lot of desire to rename it. It would be a lot of tedious busy work for everyone to rename it now. I think it is better to load up the Glossary with terms and complete another open issue for Overview.

[stevepiercy]

Classic UI uses Portlets. Volto uses blocks.

[MrTango]

I think it would be good to explain things like backend, frontend and classic-ui directly in the overview page of each section.
Glossary entries are good too, but only make sense for referencing, the entry page helps users more when they browse thru the content.

[stevepiercy]

This would be good. However if content is duplicated, then we should instead use an include to make it easier to manage content. Sometimes we need to describe the whole system to provide context to the part we are discussing, and that gets duplicated often.

[stevepiercy]

I created a new issue #1598 to reframe the installation story. I retract my original suggestion that the choice of a frontend should be made in Install. I think it is best in the Overview only.

[stevepiercy]

From #1733 (comment), here's a rough outline:

Volto

Developers and Integrators

• React-based JavaScript frontend
• REST API to the Plone backend
• Python skills not required, but helpful for modifying the backend
• Accurate and current documentation in one place
• Customization of themes is well documented and relatively easier compared to Classic UI

Editors and other end users

• Responsive, modern, fast inline editor
• Flexible layouts with blocks
• Minimal User Manual consisting only of Blocks

Classic UI

Developers and Integrators

• Python-based server-side templates for the frontend
• Customization of themes is not well-documented and relatively difficult compared to Volto
• Documentation may be out of date and scattered across multiple repositories

Editors and other end users

• WYSIWYG editor for entire pages
• Rigid layouts, based on content types
• Comprehensive User Manual for Plone 5, and nothing for Plone 6

[stevepiercy]

I've created a todo list by editing the description. I will need help from the content experts, @MrTango @fredvd @petschki @davisagli @sneridagh @ichim-david @yurj @thet @1letter @jensens and other @plone/classicui-team and @plone/volto-team members. Your mission, if you choose to accept it, is to help new users and developers choose a user interface. Here's your chance to advocate for your preference, too, especially if it is your own personal opinion.

[seanupton]

I hope my thoughts here are productive or helpful, even if they meander a bit away from the discussion of "how is each front-end branded?".

we should have learned from Coca-Cola's branding blunder

Coca-Cola's blunder was also building a "this is the new" product based on fear of missing out. Blocks (and a React dev experience, and maybe Docker too) are sort of "sweeter soda" to chase here, if you extend the metaphor. Some people need blocks (and maybe therefore an SPA), but the price of entry is high, and the bifurcation of a community's limited resources is costly.

we were staring far into the future when there would be no more Classic UI and only Volto for the frontend. Eventually the name will be correct when Classic UI gets dropped (Plone 7?)

If blocks are not one's primary use case (there are a lot of serious document-centric content management problems out there), an SPA is not as compelling, because it almost doubles the cognitive complexity of developing for an already complex stack. The single biggest barrier to Plone being adopted and retained in organizations where it is a good fit otherwise is its complexity (which has advantages and trade-offs, re: the ways Brooks describes complexity in No Silver Bullet).

I've seen React positioned as "well lots of people know it" (familiarity as entry point), but this itself does not reduce stack complexity for new developers (was it almost 20 years ago people coined the phrase "Plone tax" and pondered whether adding abstractions on top of Plone was sufficient to address?).

The notion that Classic UI is deprecated out the gates is a disheartening one, because the weight of the community for many years has been invested in its idioms. Classic (or whatever will or could grow from it) has potential beyond "incumbent compatibility" but only if we let it see that. For me, right now, Volto feels like "well, I guess I have no choice but to trade Classic UI back in to the dealership and accept this large new monthly car payment".

I would love to see more from (and frankly, give more myself to) Classic UI. The sense I get as someone who has developed for Zope and Plone primarily for the a very large part of the last 22 years (but has not contributed much back to the community lately) is that Plone's community is too small to split into two UX endeavors, and Classic UI is left with maybe a handful of devoted experts keeping things moving.

I just updated a complex application from Plone 5.2 site to Plone 6.1.0a5. After updating a bunch of jbot, theme customization, and numerous other things, I see rough edges in Barceloneta LTS and places for improvement I hope get attention. I have features I would like to add to TinyMCE's link modal. Maybe these things can get my attention, not just for my own integration, but in core. I'm pondering what I can do to help ensure there is a future for document-centric CMS cases in Plone. Volto feels like too big a break from many idioms already in use, and I want Classic to continue being viable. I know I need to contribute more back to the community; maybe this is sufficient motivation to re-engage and demonstrate my commitment to something I would like us to keep moving.

I'm not sure, I feel dissonance stating opinions here as I feel I lack a moral authority (for lack of recent contribution back to a community I have drawn so much from). I don't want to dismiss some very neat things people are doing with Volto, but I also feel a significant invested demographic of the Plone developer community may feel a bit left behind, like I do (despite a sense that Classic UI is or could be perfectly viable for a good while).

[davisagli]

@seanupton Thanks for engaging and sharing your thoughts. Some of what you were responding to was discussion on this issue from a couple years ago, so please let me summarize what I see as the current status within the community.

The intention with Plone 6 was to put Volto and Classic UI on an equal footing as choices for Plone's frontend. They both have active sub-communities of satisfied users, and each have their use cases for which they are a better fit, as you pointed out. (And I say this as someone who is working more on blocks-based sites these days.) This is why we want the documentation that is the focus of this issue, to help people pick the one that will be the best fit for them.

"Classic" does not mean deprecated. I see quite a bit of ongoing development on both the Volto and Classic UI sides. For Plone 7 the plan is not to get rid of Classic UI but to continue efforts to refactor it into a plone.classicui package that sits parallel to plone.volto. (This effort would benefit from more volunteers, but what else is new...)

I hear your concern about whether the community is big enough to support two frontends in parallel (I feel it as I try to help work on docs that cover both), but I don't think that's problem you can solve by fiat in a volunteer-based project. People are going to contribute in the area that scratches their itch, and I don't think you're going to convince users of either Volto or Classic UI to switch to the other for projects where it doesn't make sense.

It would be great to have your contributions to Classic UI and document-centric use cases.

[stevepiercy]

@seanupton to add to @davisagli's comments, there is a monthly Classic UI Team meeting in Discord.

https://discord.com/channels/786421998426521600/787254601656827924/1293566452221345883

There are also ad-hoc discussions in the Classic UI channel.

https://discord.com/channels/786421998426521600/787254601656827924

The two biggest problems with Classic UI documentation at this moment are (1) how to contribute to its core packages, and (2) how to develop a project. If I personally knew how to do either, I would write the documentation myself. We need content experts, those who are using Classic UI, to write the docs.

For Item 1, we have a pretty good start in Contribute to Plone 6 core, but it doesn't specify anything about Classic UI packages.

For Item 2, it is missing entirely from Classic UI, and we have a draft PR open that needs serious help.

I don't care whether it's just a collection of notes, in a non-English language, or on 5.25" floppy disks, let's get it in to the documentation. I will help with structure, MyST markup, and other editing.

[davisagli]

@stevepiercy It probably needs some more editing, but I tried to get the ball rolling here: #1749