[hibernate-dev] [hsearch] documentation

hi, as you know I am reviewing the Search documentation and I keep banging my head against chapter 2 (Architecture) and 3 (Configuration). This two chapters are most affected by the Search 4 changes and I think we need to rethink how we want to describe the system to our users. The current documentation is a bit of a patch work were we basically just added things introducing quite a bit of confusion. For example we in the Architecture we start talking about things like backend and reader strategy even before mentioning the IndexManager. Here is how I think we could arrange the content (correct me from wrong). The basic idea is that the IndexManager moves into focus. I think this is also already implied by the following: "The default IndexManager implementation is named transactional. This is the one mostly referred to in this documentation, unless stated otherwise, and is highly configurable as you can select different implementations for the reader strategy, back ends and Directory Providers" For me the architecture is not as follows: * each entity can be indexed into one (ore more) Lucene index * each Lucene index has a IndexManager * the index manager gives access to directory and reader provider as well as the backend to be used * when using properties of the form org.hibernate.search.<index-name>.xyz you are effectively configuring the IndexManager for the specified index * properties of the form org.hibernate.search.xyz are default values which apply for any index manager if not overridden explicitly What do you guys think about this view? In the configuration chapter I also would like to apply some other changes. For example, moving "Sharing indexes" into advanced features. We even mention in the docs that we don't recommend it, still it appears so early. Besides of that I would like to rearrange a little the different back-end configurations. Thoughts? --Hardy