Page Builder - How to add an appearance clarification

[LeanderFS]

Topic clarification/correction request

Topic Link

https://devdocs.magento.com/page-builder/docs/how-to/how-to-add-appearance.html

Description

The guide is incomplete to say the least. There is not clarification on most of the topics and concepts are very poorly explained. A couple of pointers:

• Adding a _module.less in the location indicated doesn't work and is not picked up by either grunt or a static content deploy. For example, when adding an appearance to the banner content type the added less is not being merged.
• There is no example, or written documentation about extending and/or removing elements from the parent form
• There is no example, or written documentation about adding extra elements to the form
• There is no example, or written documentation about overriding default form values
• There seems to be no possibility to hide and/or remove form fields from the parent form, or it is not documented
• The code samples used in the documentation lack critical information, e.g. on adding an appearance configuration the code sample is truncated which gives the impression that copying over all elements from the parent is not necessary. When in fact it is required to have all fields copied when re-using an existing content-type template
• The documentation refers to different content-types throughout the guide, this is very confusing and I would suggest sticking to 1 content-type for the whole guide
• There is no documentation on what to do, or what caches to clear, when updating an appearance. Resulting in a very-very slow development flow

Possible solutions

In my opinion the complete how-to section for the page builder should be re-evaluated and re-written where necessary. Because the page builder is an EE module it's coverage of tutorials/code samples is really low and therefore it's absolutely necessary to have the official documentation as clear as possible.

Additional information

It took me 5 days to figure out (trough trial and error) how to perform simple steps as adding an appearance, adding fields to the appearance form and how to update the template. I've still not figured out how to make the less styling work.

[m2-assistant[bot]]

Hi @LeanderFS. Thank you for your report. To help us process this issue please make sure that you provided sufficient information.

Please, add a comment to assign the issue: @magento I am working on this

---

• Join Magento Community Engineering Slack and ask your questions in #github channel.

[shrielenee]

Hey @LeanderFS --- Thanks for submitting this comprehensive issue to us. It sounds like you've already done the legwork and have a good headstart on the solution for documentation! Would you consider submitting a PR with this info? We'd MUCH appreciate it? Let us know how we can assist!

CC @bdenham

[LeanderFS]

Hey @LeanderFS --- Thanks for submitting this comprehensive issue to us. It sounds like you've already done the legwork and have a good headstart on the solution for documentation! Would you consider submitting a PR with this info? We'd MUCH appreciate it? Let us know how we can assist!

CC @bdenham

I'm sorry, but my english and explaining capabilities are not on a level that is required to rewrite this documentation. I understand it's a lot of work keeping the docs up to date, but seeing this is an enterprise-level module I feel it's absolutely required to, at least, keep the documentation up to date. Apparently there is a repository with pagebuilder examples, but it's horribly outdated. Half of the examples don't work anymore on current Magento versions and even contain plain html errors in the templates used. (https://github.com/magento-devdocs/pagebuilder-examples/blob/2caa3017e972785d7642771ac5fae803623c04d9/Example/PageBuilderQuote/view/adminhtml/web/template/content-type/example-quote/default/preview.html#L14)

If I had a good starting point, and some working examples of custom page builder modules (including best practises). I would gladly try and rewrite the documentation or provide some examples. But at it's current state I feel like there is too much internal Magento dev knowledge required to write a clear and concise documentation.

[dobooth]

@jcalcaben

[bdenham]

Hey @LeanderFS. I just came across this issue and want to touch base with you as it was posted before I added to, reorganized, and rewrote many sections of the Page Builder docs in February. Let me know what I or @jcalcaben can do after your new assessment.

[LeanderFS]

@bdenham Thanks for the heads-up! I've glanced over the new (and improved!) page builder docs and I feel they are way more descriptive and clear. When I have more time I'll check them in detail, but for now it has improved by miles!