Description
Prerequisites
- I have read the documentation;
Description
Many of the examples in the playground are confusing and hard to read because of the terribly chosen property names.
I would deeplink to each of the playground pages if I knew how.
-
The first example is Simple, where a property name is
boolean. This makes it look like a data type goes there, rather than the property name. -
The second example is Widgets, where different ways to display a boolean choice, are configured under the property name
boolean. This is completely non sensical and almost seems aimed at confusing the reader. -
The third example is the naming of
conditionalof one of the properties under Schema Dependencies. This makes the reader thinkconditionalis a key word.
New or returning users looking to the playground for quick examples are unnecessarily frustrated this way.
Proposal:
- Never use field types as a literal name for a property in an example.
- Don't name properties after the kind of example they're being used in such as
conditional. Use property names that resemble the fictional data points in the example (such ascredit cardorpet name), so that the reader understands it's just an example name and not a keyword.