[hibernate-dev] missing reference documentation for Hibernate Search beta

Sat Mar 6 08:43:25 EST 2010

We have spent the last two weeks on documentation for JPA 2 :) so that's coming. But yes we screwed up a bit on the doc side for this release for early adopters.

On 6 mars 2010, at 12:03, Sanne Grinovero wrote:

> It would be a nice to have for all other projects too, especially core and EM.
> Right now you've done so much work on JPA2 but - aside from
> downloading CR2 and reading blogs - there's no clue about
> documentation: not very motivating for early adopters and testers.
> 
> Sanne
> 
> 2010/3/6 Emmanuel Bernard <emmanuel at hibernate.org>:
>> yes, major.minor is good enough, you are right.
>> For trunk, I was not really planning on a nightly build. I was more thinking of (manually) pushing the docs as they are in the project trunk if there is a noticeable difference with the latest stable. But as Sanne said, he is more interested in pushing docs for beta / cr versions, not necessarily what's in trunk.
>> 
>> On 5 mars 2010, at 20:55, Steve Ebersole wrote:
>> 
>>> Wrt https://www.hibernate.org/5.html..  the plan is to eventually use
>>> index pages on docs.jboss.org/hibernate.  We have not to date simply
>>> because its way too difficult managing resource on that site.
>>> 
>>> Yes i would like to see is just the most recent docs indexed.   No clue
>>> how/if possible.
>>> 
>>> WRT the suggestion to use x.y.z I think we should be careful here.  I do
>>> not see benefit from keeping, say, 3.2.3, 3.2.4, 3.2.5, 3.2.6, 3.2.7
>>> docs all around.  IMO 3.2 is enough (latest 3.2 docs).
>>> 
>>> What is the thought process of /trunk ?  Nightly builds?  Perhaps we
>>> could do that just in english?  The build jobs already take long enough.
>>>  Maybe even just english/html or english/html_single.
>>> 
>>> 
>>> On 03/05/2010 05:46 AM, Hardy Ferentschik wrote:
>>>> As Emmanuel mentioned, we are currently only publishing the docs for GA
>>>> releases.
>>>> We used to have also the beta docs online, but stopped that due to the way
>>>> the
>>>> different docs would get indexed by Google.
>>>> 
>>>> I agree with Sanne that we should upload the documentation for the beta
>>>> releases.
>>>> http://docs.jboss.org/hibernate/project/version works fine with me. Btw,
>>>> Lucene also
>>>> publishes multiple versions of their docs. Mind you, with Lucene I had
>>>> actually cases
>>>> were I needed some extra clicks and searching to get to the right version
>>>> of the docs.
>>>> 
>>>> One idea to solve the indexing problem would be to work with robots.txt.
>>>> We could just
>>>> disallow all beta documentations from indexing. This way only the latest
>>>> GA release would
>>>> be "searchable". For the beta docs we just provide some links from
>>>> search.hibernate.org.
>>>> There is already a robots file under http://www.jboss.org/robots.txt, but
>>>> I am not sure how
>>>> feasible it is with our current processes to get this file changed.
>>>> Unfortunately, robots.txt
>>>> does not allow wildcards or regular expressions, so we would have to
>>>> explicitly exclude
>>>> the versions we don't want to have indexed.
>>>> 
>>>> Another problem with the documentation was that
>>>> https://www.hibernate.org/5.html is complicated
>>>> enough even without adding links to beta release docs. The good news is
>>>> that with the new
>>>> site (out soon hopefully) we will have a dedicated documentation page for
>>>> Search where it would
>>>> be much easier to provide some additional links.
>>>> 
>>>> Regarding automated doc uploads - the first step here would be to actually
>>>> get developer
>>>> access to http://docs.jboss.org via ssh or similar. Unfortunately, that's
>>>> not in place yet.
>>>> 
>>>> --Hardy
>>>> 
>>>> 
>>>> On Fri, 05 Mar 2010 07:13:36 -0300, Sanne Grinovero
>>>> <sanne.grinovero at gmail.com>  wrote:
>>>> 
>>>>> I like http://docs.jboss.org/hibernate/project/version
>>>>> most, as I guess I could browse available versions at
>>>>> http://docs.jboss.org/hibernate/project/
>>>>> and see which modules do exist under http://docs.jboss.org/hibernate/
>>>>> 
>>>>> and so I'd vote for http://docs.jboss.org/hibernate/search/3.2.0-BETA1
>>>>> but have no strong feelings about it, just my 2c.
>>>>> 
>>>>> About the docs, I was not thinking about the "trunk" releases of docs,
>>>>> but the beta releases would be usefull; btw so you beta test the full
>>>>> release cycle and maybe automate the documentation upload steps in
>>>>> future.
>>>>> 
>>>>> 2010/3/5 Emmanuel Bernard<emmanuel at hibernate.org>:
>>>>>> That reminds me, I don't think we ever settled on the doc scheme
>>>>>> http://docs.jboss.org/hibernate/stable/project
>>>>>> vs
>>>>>> http://docs.jboss.org/hibernate/project/version
>>>>>> 
>>>>>> On 5 mars 2010, at 11:00, Emmanuel Bernard wrote:
>>>>>> 
>>>>>>> They have never been published AFAIK, we tend to not publish docs on
>>>>>>> non final. They are bundled in the distro though.
>>>>>>> 
>>>>>>> We could change that provided we think it's useful and define some
>>>>>>> publication scheme:
>>>>>>> - http://docs.jboss.org/hibernate/search/x.y.z for stable versions
>>>>>>> - http://docs.jboss.org/hibernate/search/trunk for the latest non
>>>>>>> final version
>>>>>>> 
>>>>>>> Thoughts?
>>>>>>> 
>>>>>>> What I personally don't love with this approach is that google know
>>>>>>> nothing about stable versus trunk works and don't favorite one over
>>>>>>> the other.
>>>>>>> 
>>>>>>> On 5 mars 2010, at 10:51, Sanne Grinovero wrote:
>>>>>>> 
>>>>>>>> yes we're missing the docs of 3.2-beta
>>>>>>>> There are questions on programmatic mapping API for example
>>>>>>>> https://forum.hibernate.org/viewtopic.php?f=9&t=1003036
>>>>>>>> 
>>>>>>>> Sanne
>>>>>>>> 
>>>>>>>> 2010/3/5 Emmanuel Bernard<emmanuel at hibernate.org>:
>>>>>>>>> The docs lives in
>>>>>>>>> http://docs.jboss.org/hibernate/stable/search/reference/en/html_single/
>>>>>>>>> http://docs.jboss.org/hibernate/stable/search/reference/en/
>>>>>>>>> 
>>>>>>>>> And the link is here https://www.hibernate.org/5.html#A21
>>>>>>>>> 
>>>>>>>>> Am I missing something?
>>>>>>>>> 
>>>>>>>>> On 5 mars 2010, at 10:26, Sanne Grinovero wrote:
>>>>>>>>> 
>>>>>>>>>> Hello,
>>>>>>>>>> I am seeing an increasing rate of questions on the Search forum
>>>>>>>>>> about
>>>>>>>>>> well documented stuff;
>>>>>>>>>> I just noticed that I can't point them to the documentation is it's
>>>>>>>>>> not there.
>>>>>>>>>> 
>>>>>>>>>> I could edit the wiki myself to add some URL, but I can't find out
>>>>>>>>>> the
>>>>>>>>>> missing link either as it's all redirecting now to jboss.org,
>>>>>>>>>> and it appears to be missing.
>>>>>>>>>> 
>>>>>>>>>> could someone look into this?
>>>>>>>>>> 
>>>>>>>>>> Thanks,
>>>>>>>>>> Sanne
>>>> 
>>>> 
>>>> _______________________________________________
>>>> hibernate-dev mailing list
>>>> hibernate-dev at lists.jboss.org
>>>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>>> 
>>> --
>>> steve at hibernate.org
>>> http://hibernate.org
>>> _______________________________________________
>>> hibernate-dev mailing list
>>> hibernate-dev at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>> 
>> 
>> _______________________________________________
>> hibernate-dev mailing list
>> hibernate-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>> 