[hibernate-dev] [hsearch] documentation

[Hardy Ferentschik]

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