We received another issue with clarity on docs - please let me know what details we would need here to reply to customer needs. 

Here's another topic that I think deserves better developer
documentation: form fields, and itemProviders in particular.

I'd like to write a custom itemProvider and find the involved
concepts/java API difficult to understand.

The situation is similar to UI context. I have no problems to adapt
existing code but don't understand how the involved classes work, e.g.
ItemProviderStrategy, ItemProviderDefinition, etc.

The comments in the corresponding classes are also of little help (and
sometimes even misleading). See the comment for ItemProviderStrategy for
a good example: super cryptic and in part contradictory.
https://git.magnolia-cms.com/projects/PLATFORM/repos/ui.pub/browse/magnolia-ui-framework/src/main/java/info/magnolia/ui/editor/ItemProviderStrategy.java
Could you add docs that make clear how the Magnolia java side of forms
works, like what you did for the UI Context API?