ion-java icon indicating copy to clipboard operation
ion-java copied to clipboard

De-emphasize Facet in other documentation (e.g. IonReader)

Open jobarr-amzn opened this issue 1 year ago • 1 comments

In recent usability studies, new users were confused by the documentation references to Facets, and tried to find the right Facet for an instance of IonReader to solve their problems even when Facets were completely irrelevant.

jobarr-amzn avatar Jul 03 '23 23:07 jobarr-amzn

Personally, I find Facets, even when used as intended to be confusing.

I understand the goal is to encapsulate the implementation, but the indirection is difficult. Specifically, it's really hard to "see" what facets each object provides from the code.

I would suggest an entirely different mechanism for a future API.

rmarrowstone avatar Jul 05 '23 17:07 rmarrowstone