Add explanation of general concepts, HOWTOs to the documentation


The current documentation is more of a "reference", allowing a user to easily find all the features offered by Hibernate Search. It does not, however, allow a new user not familiar with full-text search to easily find straightforward, exhaustive solutions to his basic use cases.

In order to make life easier for new users, we should provide:

  1. Some explanation of the general concepts that must be understood before one uses Hibernate Search. Mainly text analysis, but maybe there are other concepts that should be explained.

  2. Some HOWTOs, i.e. sections about "how to do X", X being a common use case. In particular how to implement autocomplete, how to perform faceting using range/terms aggregations, or how to perform “nested” searches (should be introduced differently, but we need to present the use case and state that the solution is “nested documents”).

Some of the content could be extracted from existing resources:

It is important to keep it simple and concise, otherwise users are likely to simply never read it. We can always point to other resources for more in-depth explanations.

Maybe these are already part of the documentation. If that's the case, we should really make them more obvious and easier to find, because a lot of questions on stackoverflow come from users that obviously don't understand the basic concepts, or are having a hard time addressing their use case, and I often cannot link them to a section of the documentation explaining what they need.

Note that we don't have to put it all in the documentation right away. Some preliminary attempts to explain specific topics in blog posts could allow us to get feedback, and would could (later) integrate the content to the documentation.





Yoann Rodière


Yoann Rodière



Suitable for new contributors


Pull Request


Feedback Requested



Fix versions