HSEARCH-1644

Docs updates ! :-)
 - https://hibernate.atlassian.net/browse/HSEARCH-1644

Because I needed to switch to more urgent topics. If you don't accept incremental improvements, you're opting for no improvements.. sad as I think there are many good things in here.