9:19 a.m.
Hi,
IMO we should rethink how we describe the architecture of Search and especially its
extension points.
I think for Search 5 we will need to review/rewrite the documentation (maybe as part of
moving to asciidoc) and clear out some
of the ambiguities we have in the used terminology.
For example, ‘backend’. Technically it is the implementation of BackendQueueProcessor, but
I think we sometimes used the
term in the wrong context as well, for example when we talk about the "Infinispan
backend” which is really a DirectoryProvider.
Speaking of the latter, my understanding is that we wanted to move away from
DirectoryProvider (at least from a configuration/
documentation point of view) and consistently refer to IndexManager.
These are just two examples of various major and minor inconsistencies in how we describe
Search. I think we really should
spend some time and work out the terminology we want to use and weed out the
documentation. Maybe this is something
everyone can just keep in mind for a while to think about.
Should we create an issue for this where we can collect ideas on what needs to be
changed?
—Hardy
11:17 a.m.
On 19 December 2013 15:19, Hardy Ferentschik <hardy(a)hibernate.org> wrote:
Hi,
IMO we should rethink how we describe the architecture of Search and especially its
extension points.
I think for Search 5 we will need to review/rewrite the documentation (maybe as part of
moving to asciidoc) and clear out some
of the ambiguities we have in the used terminology.
+1 !
My hope would be that we'd first move to asciidoc, so to minimize the
effort of the reorganization (more on this below).
For example, ‘backend’. Technically it is the implementation of BackendQueueProcessor,
but I think we sometimes used the
term in the wrong context as well, for example when we talk about the "Infinispan
backend” which is really a DirectoryProvider.
We can certainly clarify, and I did talked frequently about an
"Infinispan backend" as I'm working on such a thing.
The difference is quite clear in my mind so I don't think I would have
messed up the terminology but ok I guess not all my emails are well
crafted.
Speaking of the latter, my understanding is that we wanted to move
away from DirectoryProvider (at least from a configuration/
documentation point of view) and consistently refer to IndexManager.
+0,8 :-)
I agree we should be moving in that direction, but we can't get
completely rid of the concepts.
We probably should review how the user actually configures these
things; we introduced the IndexManager notion during 4.0, but for
backwards compatibility we kept explicit options around
DirectoryProvider and Backends, and these are accepted if no IM is
configured.
Still even back then the intention was to develop a collection of
IndexManager(s) to phase away the need to explain what should be just
an implementation detail. However these "implementation details" are
important to understand for proper tuning and to be able to make a
sound choice of deployment architecture, so I don't think we'll be
able to get rid of them - especially in the architecture chapter.
We also need to make sure people on our team understand these terms,
as these are our means for talking to each other, but I hope that goes
without saying as it's not the first time or the last that we'll see
people using names of interfaces in technical discussions.
These are just two examples of various major and minor
inconsistencies in how we describe Search. I think we really should
spend some time and work out the terminology we want to use and weed out the
documentation. Maybe this is something
everyone can just keep in mind for a while to think about.
Should we create an issue for this where we can collect ideas on what needs to be
changed?
Creating two issues as a starter:
- https://hibernate.atlassian.net/browse/HSEARCH-1471 Migrate
documentation to asciidoc
- https://hibernate.atlassian.net/browse/HSEARCH-1472 Broaden
collection of built in IndexManager implementations to simplify choice
of sensible configurations
Needless to say HSEARCH-1472 implies a significant documentation work,
we can see after these are done if you want to add more?
On asciidoc: I'd be tempted to say we should do it first to lower the
cost of any further patches, but I'm not too happy in considering it a
blocker for 5.0 .. thoughts?
Cheers,
Sanne
—Hardy
_______________________________________________
hibernate-dev mailing list
hibernate-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hibernate-dev
2:08 a.m.
On 19 Jan 2013, at 18:17, Sanne Grinovero <sanne(a)hibernate.org> wrote:
On 19 December 2013 15:19, Hardy Ferentschik
<hardy(a)hibernate.org> wrote:
> Hi,
>
> IMO we should rethink how we describe the architecture of Search and especially its
extension points.
> I think for Search 5 we will need to review/rewrite the documentation (maybe as part
of moving to asciidoc) and clear out some
> of the ambiguities we have in the used terminology.
+1 !
My hope would be that we'd first move to asciidoc, so to minimize the
effort of the reorganization (more on this below).
A move to asciidoc might be beneficial, but not a requirement.
> For example, ‘backend’. Technically it is the implementation of
BackendQueueProcessor, but I think we sometimes used the
> term in the wrong context as well, for example when we talk about the
"Infinispan backend” which is really a DirectoryProvider.
We can certainly clarify, and I did talked frequently about an
"Infinispan backend" as I'm working on such a thing.
The difference is quite clear in my mind so I don't think I would have
messed up the terminology but ok I guess not all my emails are well
crafted.
Well, for starters we could change the description in the infinispan module pom which says
“Hibernate Search Infinispan Backend”.
In the current light I would even suggest to rename the module directory to infinispan-dp
or infinispan-directory-provider. Much more
telling than infinispan.
> Speaking of the latter, my understanding is that we wanted to
move away from DirectoryProvider (at least from a configuration/
> documentation point of view) and consistently refer to IndexManager.
+0,8 :-)
I agree we should be moving in that direction, but we can't get
completely rid of the concepts.
It is not necessarily a matter of getting rid of things, but how you present them. This
might also require some coding to offer,
for example, an index manger implementation for all our standard setups. However, in the
end there should be a cohesive way
of doing things as long as you stick to the provided setups. The concept of a
DirectoryProvider can then become a advanced
topic. We could for example have a section (topical guide ;-)) how to bake your own
IndexManager.
We probably should review how the user actually configures these
things; we introduced the IndexManager notion during 4.0, but for
backwards compatibility we kept explicit options around
DirectoryProvider and Backends, and these are accepted if no IM is
configured.
IMO there is no way to know to determine how users use it. That depends on which version
they started using Search
and which documentation/examples they have seen. The more interesting question is, how we
think it should be configured.
On a related note, we have been discussing abandoning the properties approach and moving
to a more structured configuration
approach (xml, yaml, …). In this case I see a configuration being ways more index manager
centric as well. Users would either just name a
default configuration or they configure their own index manager.
I don’t think we will be able to transition to this type of configuration for the initial
Search 5 version, but in the light of these plans it might
make sense to weed out some of the configuration options which we kept for backwards
compatibility.
Still even back then the intention was to develop a collection of
IndexManager(s) to phase away the need to explain what should be just
an implementation detail.
+1
However these "implementation details" are
important to understand for proper tuning and to be able to make a
sound choice of deployment architecture, so I don't think we'll be
able to get rid of them - especially in the architecture chapter.
I think a lot can be moved into a advanced user chapter
—Hardy
4022
days inactive
4023
days old
2 comments
2 participants
participants (2)
-
Hardy Ferentschik -
Sanne Grinovero