[hibernate-dev] [Search and more] What is new in a give release

[Steve Ebersole]

This makes me a little nervous in the case we ever publish other
manuals/docs.

IMO the better option is to publish an index.html that is currently just a
redirect to the User Manual

On Thu, Sep 14, 2017, 7:55 AM Vlad Mihalcea <mihalcea.vlad at gmail.com> wrote:

> Hi,
>
> To be able to load the User Guide like this:
>
> https://docs.jboss.org/hibernate/orm/5.2
> <https://docs.jboss.org/hibernate/orm/5.2%60>
>
> we have two options:
>
> 1. Either we rename the User Guide to index.adoc so that it will become
> index.html.
> 2. We leave it as-is, but when we copy the docs to JBoss, we also copy the
> User Guide as index.html as well. This will allow our users to retain
> bookmarks they've created since we published the new User Guide.
>
> Let me know which one do you prefer.
> Vlad
>
> On Thu, Sep 14, 2017 at 3:34 PM, Steve Ebersole <steve at hibernate.org>
> wrote:
>
>> Yoann,
>>
>> First thanks for the work on this.  I think it looks worlds better.  A few
>> minor things:
>>
>>
>>    1. Not sure of the source for this, but can we fix these doc link for
>
>
>>    5.2 from `
>>
>> https://docs.jboss.org/hibernate/stable/orm/userguide/html_single/Hibernate_User_Guide.html`
>> <https://docs.jboss.org/hibernate/stable/orm/userguide/html_single/Hibernate_User_Guide.html>
>>    to `https://docs.jboss.org/hibernate/orm/5.2`
>> <https://docs.jboss.org/hibernate/orm/5.2>?  Also, why https?  Not
>>    sure it matters, just found it odd
>>
>    2. Much of the information on that ORM releases page is, in turn,
>
>
>>    version/series specific.  Any reason why those pieces of information
>> are
>>    not part of the series?  Either in the synopsis on the releases page
>> or on
>>    the specific series page, or both.  Specifically
>>
>       1. "Compatibility Matrix" - the fact that its a table based on series
>
>
>>       is a good indicator it is all series specific ;)
>>
>       2. "Maven Repository" - I'd personally prefer to have this as part of
>>       the series info
>>    3. I think the individual series pages are missing a key piece of
>
>
>>    information... the "synopsis" of that series.  I guess partially this
>> fits
>>    under "what's new"
>>
>> Other than these minor things I love it.  Great job!
>>
>> P.S. another question is whether (and if so, how) to apply the same
>> treatment to the Documentation info in terms of the nav links.
>>
>
>> On Thu, Sep 14, 2017 at 7:05 AM Yoann Rodiere <yoann at hibernate.org>
>> wrote:
>>
>> > I polished the changes, applied them to all projects (ORM, OGM,
>> Validator,
>> > Search), and sent a PR:
>> > https://github.com/hibernate/hibernate.org/pull/126
>> > Could you guys review it? Mainly I'd need one person per project to
>> check
>> > they agree with the changes, especially in their project's section.
>> > Also, there's still a bit of work to do for each project, mainly filling
>> > in missing metadata (see the PR).
>> >
>> > Yoann Rodière
>> > Hibernate NoORM Team
>> > yoann at hibernate.org
>> >
>> > On 14 September 2017 at 10:38, Emmanuel Bernard <emmanuel at hibernate.org
>> >
>> > wrote:
>> >
>> >> On Wed 17-09-13 10:55, Sanne Grinovero wrote:
>> >>
>> >>> On 13 September 2017 at 10:51, Yoann Rodiere <yoann at hibernate.org>
>> >>> wrote:
>> >>>
>> >>>> It's more the number of columns, what if you add more version,
>> should I
>> >>>>> scroll horizontally? Also releeases tend to be shown vertically with
>> >>>>> version in desc order. This model breaks a bit this habit.
>> >>>>>
>> >>>>
>> >>>>
>> >>>> At least versions are in desc order :D
>> >>>> More seriously, I was more worried about the number of dependencies
>> than
>> >>>> about the number of series. We don't want to maintain a hundred
>> >>>> branches, so
>> >>>> we'll probably try to keep the number of series to a minimum, but we
>> do
>> >>>> want
>> >>>> to offer as much as possible to users, so we may offer many different
>> >>>> integrations, and thus many different dependencies. Just think if the
>> >>>> ORM
>> >>>> team wants to display supported versions of each DBMS... So I thought
>> >>>> showing versions horizontally would be more future-proof.
>> >>>> I'll try to add horizontal scrolling to the table. The oldest
>> releases
>> >>>> may
>> >>>> not be displayed, but then those are not the one we want to
>> advertise,
>> >>>> so...
>> >>>> And in any case, we have limited horizontal space, so we have to hide
>> >>>> *something*.
>> >>>> About phones, I think bootstrap has something, I'll give it a try.
>> >>>>
>> >>>> On "Downloads" we only want to promote the active branches; have some
>> >>>>> basic series descriptions but way more ecclectic than the releases
>> >>>>> descriptions. We make them cross-linked and everyone is happy?
>> >>>>>
>> >>>>
>> >>>>
>> >>>> Sure, we can do that. But the "downloads" page will essentially be a
>> >>>> stripped-down version of the "releases" page.
>> >>>>
>> >>>
>> >>> +1 since maintenance is automated I see no problem with a little
>> >>> redundancy.
>> >>>
>> >>
>> >> I'm not sure two pages is really solving the problem. It looks like you
>> >> don't want to make a choice. But I don't have a pro/con opinion.
>> >> My real concern is since you will have two pages, what's the navigation
>> >> logic? How do you reach each on of these pages?
>> >>
>> >> Just thinking out loud here but I think the one way to solve long
>> >> standing Steve objective is indeed to have per series sections of the
>> >> website (including download, documentation, migration guide)
>> >> And a top nav for "latest/promoted" releases (like we have today
>> >> really).
>> >> How do you merge the two navigation wise is what I don't know.
>> >> This is for later work anyways.
>> >>
>> >
>> >
>>
> _______________________________________________
>> hibernate-dev mailing list
>> hibernate-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>>
>