Docs: formatting and clarifications

 - https://hibernate.atlassian.net/browse/HSEARCH-1670
 - https://hibernate.atlassian.net/browse/HSEARCH-1671