[hibernate-dev] [hsearch] documentation

[Sanne Grinovero]

Hi Hardy,
commented inline:

On 11 October 2011 14:45, Hardy Ferentschik <hardy at hibernate.org> wrote:
> 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.

+1

> 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

but also multiple entities in the same index is an option.

> * each Lucene index has a IndexManager

yes, and a unique name to identify it.

> * the index manager gives access to directory and reader provider as well
> as the backend to be used

This is a tricky point. Generally this is correct, especially for the
default IndexManager, but alternative implementations don't have to
use a backend, or at least not one as defined by
BackendQueueProcessor:  we don't expose this interface so if someone
wants to implement an IndexManager using a different approach, they
can. And we will be providing some in 4.1+.

> * when using properties of the form org.hibernate.search.<index-name>.xyz
> you are effectively configuring the
>   IndexManager for the specified index

+1

> * properties of the form org.hibernate.search.xyz are default values which
> apply for any index manager if
>   not overridden explicitly

warning it's actually
"hibernate.search.default."

 a- no "org." in the front
 b- it must end with ".default" to be picked up by other IndexManagers

on a) : shall we relax this and allow "org." prefix too? This bytes
myself periodically
on b) : I really think this ".default" business got out of hand; it
made sense in initial days as there wasn't much to configure, but
nowaday? Is it still self-speaking that "default" relates to the
IndexManager / indexes ?

We have an issue open around reviewing configuration properties, this
thought was one of the reason to open it:

HSEARCH-859 - Review names and composition of configuration properties

So let's point out more property names which could be improved if you hit one.

> What do you guys think about this view?

Yes I think this clarifies a lot. Keep in mind that index names might
have a dot in it, and we allow inheritance from the parent named (for
example for sharding) and inheritance from the default index settings.

> 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?

Sounds all good. I'm not touching docs myself to avoid conflicts, but
if you want to assign me some tasks in isolated chapters.

Sanne

>
> --Hardy
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>