Select Option By * Documentation is worse than poor

Feedback & Reviews Documentation
,
1

I believe it’s high time the documentation for the various Select Option By— APIs were rewritten to reflect correctly what they actually do.

Problem

Visitors and especially new users are led to believe these APIs target any kind of list. And that’s not surprising given the way the docs are written:

image
image818×217 13.4 KB

image

Technical documentation needs to be clear and precise. The use of the term “list” misleads the user into thinking the API should be able to target <ol> and <ul> elements (Ordered and Unordered Lists; whereas, in fact, the APIs do not – they can only target <option> elements inside a <select> element. Nowhere does the documentation make that absolutely clear. :angry:

Commentary

I’d be surprised if all new-user problems associated with this API set didn’t comprise of anything less than 5% of the postings here. This one is just the latest – when I read her first paragraph, my heart sank…

When I went on to read the rest of her post and saw the pains she went to just to ensure she’d posted everything we could possibly need to help her, I had to go read the docs (again) just to see why so many people are led to making the same dumb* mistake. What I found is how I described it above: the documentation is worse than poor.

So. Please FIX ASAP. Thanks.

*dumb: that’s a reflection on the docs, not the users.

2 Likes
2

Thank you for sharing this. I am forwarding this internally for review.

Agreed- documentation needs to be clear and concise.

I will keep you apprised of progress. For the time being I will close this thread. When we have an update we will post and @mention you.

Best, Sara