Exceptionally deficient documentation and developer experience

Question

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.

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?

Jeff.Thompson@arlingtontx.gov_arlingtontx · Answer

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.

D_Atkins · Answer

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.

Justin_Greco · Answer

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.