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:
# 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. # Some HOWTOs, i.e. sections about "how to do X", X being a common use case. In particular how to implement autocomplete, 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:
* This explanation of text analysis: [https://stackoverflow.com/questions/52084491/how-to-retrieve-exact-search-results-with-multiple-query-strings-in-hibernate-se/52092902#52092902] * This explanation of how to change data in batches when using Hibernate Search (unless we add “auto-flushing” to Hibernate Search upon Hibernate ORM flushes as mentioned in HSEARCH-3360, in which case we will just need to mention the potential memory issues of not calling \{\{flushToIndexes()\}\}): [https://hibernate.atlassian.net/browse/HSEARCH-1350?focusedCommentId=103644&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-103644] * This presentation explaining full-text search in the Lucene world (in French, I'll have to translate it): [https://yrodiere.github.io/presentation/hsearch-es-jug-strasbourg/] * A detailed explanation of how indexed embedded settings are composed. It seems the documentation was not clear enough, see [https://discourse.hibernate.org/t/out-of-memory-errors-when-indexing-a-large-entity/2286/7?u=yrodiere] 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. |
|