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 https://github.com/plone/plone.volto/pull/94#issuecomment-1297188976

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 https://github.com/plone/documentation/issues/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 https://github.com/plone/plone.volto/pull/94#issuecomment-1298915136.

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 https://github.com/plone/documentation/issues/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.