On 19 December 2013 15:19, Hardy Ferentschik <ha...@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@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
