docs: case-insensitive Pin.name filter

[lidel]

This PR updates description of name filter and removes ambiguity, as noted in #45 (comment) by @andrew and @obo20

The rationale for going with case-sensitive is that it is more performance out of the box, does not require any additional indexes or optimizations, and one can use third-party case-sensitive identifiers (other than CID).

Case-insensitive makes it easier to search and returns not false-negatives, but comes with a risk for bugs when a search results in table scan even when there is an index on the name column.

Let's review which way to go in this PR.

Update: we went with case-insensitive

[andrew]

👍

[jacobheun]

I get the performance aspect of this, but if I was implementing the API I'd want to and would violate this as the user experience is not great. The whole point of naming a pin is to create a human identifiable association to it. If I pinned a collection of photos from 2018 and called it "Photos-2018", because I'm human and name things inconsistently, and couldn't search for it with 'photos' that would be frustrating.

I'd much rather see the recommendation be for case-insensitive searching purely for usability reasons.

[lidel]

Both approaches have merit, I wonder what would be better:

• making name case-insensitive (and making it useless for case-sensitive identifiers)
• supporting both: case-insensitive name and add separate filter nameCaseSensitive – needs better... name)

Thoughts?

[jacobheun]

supporting both: case-insensitive name and add separate filter nameCaseSensitive – needs better... name)

I'm not seeing the value this provides that would justify the added complexity. You mentioned 3rd party identifiers being restricted to case-insensitive usage if we went case-insensitive only, but I don't see the harm in that or a good reason to use a identifier generator for pin names to begin with, did you have something in particular in mind?

As I see it, the point of a pin name is to create a meaningful label so that I will know what the content is for the given CID. As long as the name is meaningful to the end user, case sensitivity doesn't really matter during a query. You'd still be able to view the casing on the name when it's returned in the search results, if that has meaning to you, but finding the content by name becomes much easier.

[lidel]

@obo20 @andrew @jacobheun I flipped it to be case-insensitive:

• Agree its main value of name field is ease of finding pin by human-readable labels, and presenting them in UIs, so going with case-insensitive improves UX by removing the problem of false-negatives.

• The case-sensitive identifiers I mentioned could be something that is specific to an app, but one could either re-encode them to case-insensitive form, or use Pin.meta[custom_id] instead.

Mind reviewing again?

[andrew]

👍

[lidel]

As this is only clarifying change to docs, I feel its safe to merge