devdocs Inadequate description, overview, usage of UI components

Inadequate description, overview, usage of UI components

Open adamlavery opened this issue 3 years ago • 1 comments

Is there an existing issue for this?

[X] I have searched the existing issues

Which topic?

https://devdocs.magento.com/guides/v2.4/ui_comp_guide/components/ui-insertlisting.html

What's wrong with the content?

As you say in the overview, naming and correct configuration is critical when comes to using UI components, yet you have nothing to describe how it all hangs together. Just a load of simple examples that are pointless and disjointed. Let's take the noted topic:

Here you apparently list InsertListing configuration options but then provide examples that reference tags you haven't mentioned e.g. you use datascope and ns in the example but do not list them as valid tags. Hence no understanding that they need to be included or what they should be set to.

Further, the descriptions would flummox Einstein! What does "Enable exporting from the insertListing’s externalValue to the inserted Listing aggregated value." even mean? Same for most of descriptions. Without properly setting context by guiding developers through the basics, with concrete, useable examples, these descriptions are just a jumble of words.

Further still, you get something wrong, which is all too easy given the inadequate documents, and instead of a useful error pointing to what's wrong we just get obscure code failure (and pointless "something went wrong") with no clue where to start looking. I guess Adobe has employed a lot of ex-Apple developers!

UI components are no doubt highly flexible, but 2/10 for explaining how to work with them. It's not just about the what, the why is just as if not more important.

What changes do you propose?

Rewrite! Start by adding a clear overview of how UI component naming and configuration works (the why) before diving into details (the what). How does what goes into the config relate to what else we have to provide e.g. file names, locations?

Introduce terms before using them. For example, when reading up on InsertListing, we have no idea what "InsertListing's externalValue" or "Listing aggregated value" are. Explain them.

Cover all possible configuration options for each component on each component; don't assume we may have encountered it elsewhere. Either that or have a page covering common options that apply to and work the same for all components.

Use proper examples that are fully explained. "Hello world" style examples that have no use in the real world really don't help, because they are only ever going to be part of the full data flow solution.