Docs: formatting and clarifications

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

Could you maybe quickly sum up what change is required and why.