To answer your question, I refreshed my docs client and rebuilt the docs. Then I went to the Developer's Guide to look up the material on how to get Derby to sort data in a case-insensitive way. The first place I looked was in the table of contents under "Localizing Derby". I think that a lot of people will go to that section first. Many people coming from other databases will think of sort-order as an attribute of individual table columns, not a bulk attribute of the entire database.
However, the material is under the "Working with the database connection URL attributes" topic. This probably makes a lot of sense for people who are familiar with Derby. But newbies aren't going to know to look for case-sensitivity information under a topic on connection URLs. If only we had a document index, this would be less of a problem.
I think that people will look for this material in a couple places:
1) Where I initially looked, under "Localizing Derby" in the Developer's Guide.
2) In the Reference Guide section titled "Data type assignments and comparison, sorting, and ordering".
3) Maybe even under the "CREATE INDEX statement" topic in the Reference Guide.
At a minimum, I'd recommend adding pointers from the above topics to the relevant material. I think that the pointers for (1) are handled by the work you did on
DERBY-4627. We could probably do with some pointers for (2) and (3).
But at the end of the day, it would really be great if this material popped when you scanned the table of contents. I wonder if it's worth putting a dummy section under "Localizing Derby" just so that it pops when the reader looks there. The dummy section could just forward the user to the relevant material. On the other hand, that would be trying to make the table of contents function like an index and so is the beginning of a slippery slope which we may regret later.
Those are my $0.02. Thanks.