[DOC] Duplicate content in the docs

[marbru]

As a newcomer to the project, I found very confusing that in the docs, in the "getting started" section we have the same tutorial for the hero component repeated twice as two different sections: https://djangocms-frontend.readthedocs.io/en/stable/tutorial/template_components.html and https://djangocms-frontend.readthedocs.io/en/stable/tutorial/custom_components.html - both sections could be merged into one.

[marbru]

I started doing some cleanup of these sections in this PR: #317

Then I actually realized that they are not really duplicated, it's just that they build the same component in two very different ways. But a couple of issues were making things confusing at first sight.

First, the overloading of the word "custom frontend component" / "custom component": both template-only components and CMSFrontendComponent components are custom frontend components! The latter does not have a proper name, so we keep using the word "custom component" to refer to them, when this is a very generic name that applies to template components as well. I referred to them as "custom CMS frontend components" in the PR, but this IMO is still not clear enough. I propose they should be given a more specific name: perhaps "CMSFrontendComponents" or "form components".

Secondly both tutorials had an introductory text stating the benefits of custom frontend components, generically. And this was followed by an identical installation section, plus a "hero component" tutorial that, unless you look closely, you don't realize they are doing it with different approaches. So to a newcomer, it looks like they are duplicate tutorials indeed.

In the PR I have removed the generic intro text and installation instructions (installations now are only in the first tutorial, which has been renamed to "Installation and usage with built-in components"), and now have introductory text which specifically covers the differences with template/form components. The same hero code examples are kept, but hopefully now it's clear that we are building the same component with different implementations.

For further clarity, my proposal would be to properly give a more unique name to the "CMS frontend components" (the ones with a cms_component.py class). I like "form components". This can be done in a followup PR perhaps.

[fsbraun]

Thanks very much, @marbru ! I appreciate the rigor and it would be great if we could use one word and only one word for one concept.

What do you think of:

• "Built-in components" for the (largely Bootstrap 5-based) standard components in "contrib".
• "Frontend components" for the CMSFrontendCompnent-based custom components (congruence of class and name)
• "Template components" for the template-based custom components

We can add "CMS" in front, but if so, probably for both. What do you think?

Maybe we can make a table somewhere in the intro to clarify the nomenclature and use?

[marbru]

The problem with "frontend components" is that it is a generic webdev term... both built-in components, template components or even a tailwind blob can be referred to as "frontend components". But I guess if the name is already very stuck with the community then changing it to something very different might be too disruptive.

TBH I'm not a super fan of adding "CMS" in front, makes the names too verbose.

There's already a good intro clearly describing each type of component: https://djangocms-frontend.readthedocs.io/en/stable/tutorial/index.html but it is kinda hidden: you have to click on "getting started", which you might miss (I did at first). Perhaps this could be moved to the landing page for extra clarity.

And maybe simply changing the title of the tutorials:

• Installation and usage with built-in components
• Simplified component creation with templates
• Building custom components with form classes

So they are all "frontend components", it's just "some are built from templates and some from code"

Plus the rest of the cleanup done in the PR (specific tutorial intros and remove duplicate sections), would be enough improvement .

[fsbraun]

When I use "frontend" I refer to the package djangocms-frontend...

We would still need a word for the three categories of components.

• Built-in (frontend) components
• Form-based components
• Template components

This might be a good compromise.

I like the proposed tutorial titles.

[marbru]

In the landing page and across the docs the term "frontend components" is often used generically (mostly in introductory texts). Examples:

django CMS Frontend is a versatile plugin suite for django CMS that facilitates the easy creation of reusable frontend components.

Effortless Development of Custom Frontend Components: Create reusable frontend components with ease, utilizing simple templates and declarative form classes.

That's why I think the term is confusing for also naming the form-based components specifically. At least for newcomers.

I think the new names you suggested work! "form-based" is unique and descriptive, no room for confusion.

Guess this quote never gets old:

There are only two hard things in Computer Science: cache invalidation and naming things.