Exceptionally deficient documentation and developer experience

[Higgsy]

It appears that the screenshot below constitutes the complete and total extent of documentation for an entirely new framework, "@arcgis/core":

Actually, its apparent that this forum does not support screenshots, so I can only link you to the available documentation in question here. 

The documentation links to a repository with several rudimentary examples, none of which make even an attempt to document the API. I have deduced that the below code block should render a map, with a legend, zoom, and search bar, but unfortunately it doesn't.

<arcgis-map item-id="02b37471d5d84cacbebcccd785460e94">
          <arcgis-zoom position="top-left" />
          <arcgis-search position="top-right" />
          <arcgis-legend position="bottom-left" />
</arcgis-map>

Being a developer, I am of course interested in doing more than copy and paste an example from a lone, disinterested example repository. Even worse, there appears to be a cyclical link in the documentation workflow. The website docs above link to the GitHub repository, which links to the NPM package, which links back to the documentation website. None of these artifacts make any attempt to document the API.

Unfortunately, I have nowhere else to look. Are there any more docs? Are they coming soon? Do people really use the new "@arcgis/core" API?

[JoelBennett]

You might be looking for this:

https://developers.arcgis.com/javascript/latest/references/map-components/

I suppose it would typically be arrived at by going to the ArcGIS Maps SDK for JavaScript documentation, clicking "References" near the top-right, and then clicking the Map Components tile.

[JeffreyThompson2]

Please adjust your attitude. This forum is maintained by volunteers, most are not ESRI employees. It is a place where professionals seek help from other professionals. I get that learning a new framework can be frustrating, but you won't get very far in the workforce with an attitude like that.

On the page you link, there is a very clear step stating that you must give your body and/or the Map Component a height in CSS or it will not be visible. I am 99% certain you did not do that. It is a common rookie mistake. I forget about it sometimes, too. I could have told you this yesterday, but your attitude put me off wanting to help.

[D_Atkins]

I agree with your perspective on attitude and approach, but I strongly disagree with your assessment of the documentation linked.  Nothing on the "Configure CSS" page or sample indicates that a height:100% is required.  Coming from most other frameworks and documentation, that might as well be CSS boilerplate.

For a personal example, chase the 'popup' configuration through the new arcgis-map component.  Not long, and you're back in core/widgets.  Click around again, and you're misguidedly looking at core/map and core/view...  "just learn the difference" you might say; "exceptionally deficient documentation" others are entitled to reply.

And just why is height: a required tag everywhere (i.e., FeatureTable grid) -- this in and of itself goes against the web standard of height:auto?  Suppose there is a good reason for this anti-pattern, then it certainly deserves more callouts, in more places (as in, everywhere it may be relevant) in the documentation.

This community and the knowledge base it has created is invaluable (half of any ArcGIS development searches will land here), but it is not a substitute for clear and detailed documentation.

[JeffreyThompson2]

I may have been a little overly harsh on @Higgsy. They do have a point that the documentation on the documentation on the Component side of the API is a bit lacking, especially compared to the excellent documentation that we have been used to on the Widget based API. 

As for your question, @D_Atkins, I believe the reason that Components require a CSS height is that they are loaded through the Virtual DOM and so have no inherit height or other CSS properties on the actual DOM, which is also why height: auto will not work either. The text in the screenshot does indicate that it is necessary to make the Components visible, but making this more prominent and providing an explanation would be good improvements to the documentation. 

[Justin_Greco]

Without seeing a sample of your code, its a bit difficult to help you out.  But since you are mentioning "@arcgis/core", I am wondering if you are forgetting to install "@arcgis/map-components".  The sample you included is using components and not the deprecated widgets provided with "@arcgis/core".  You just need to install "@arcgis/map-components", since the core SDK gets installed with it.

As for the documentation, you might not have seen the SDK Reference and the Samples

I have always found the documentation to be exceptional.