The one drawback to splitting out a mapping guide from the user guide (and
it is a big one) is the inability to link to discussions in the user guide,
and vice versa. Instead I have to keep saying things like "For details see
XYZ in the <citetitle>Hibernate User Guide</citetitle>". I would
as a user, that would get old after a while - not being able to just click
On Mon, Aug 3, 2015 at 7:15 PM Steve Ebersole <steve(a)hibernate.org> wrote:
Well Identifiers in the mapping guide still needs some work. I guess
that into category (b). TBH I do not know how much of "derived identities"
I will document this time around. If someone more familiar/comfortable
with explaining that stuff wanted to take a shot I would not argue :)
On Mon, Aug 3, 2015 at 6:55 PM Steve Ebersole <steve(a)hibernate.org> wrote:
> So the documentation is getting along. If people could start looking it
> over that would be great. If people are willing to pick up remaining
> topics, even better!
> So the 2 old docs (manual and devguide) are now 3 much more focused docs:
> 1) Hibernate User Guide - much of the information from the old manual
> with lots of TLC and updates.
> a) Chapters I think are in good shape: Architecture,
> DomainModel, Bootstrap, PersistenceContext, Database_Access, Transactions,
> JNDI, Portability.
> b) Chapters that need some work: Locking, Fetching, Caching, Events,
> Multi_Tenancy, OSGi, Envers.
> c) Chapters that either still need writing or new major work: Batching,
> HQL, Criteria, Native Queries
> This stuff is in documentation/src/main/docbook/manual, although I
> expect to rename manual to userGuide to better align. To build it, run
> `gradle renderDocBook_manual` and look in
> 2) Hibernate Domain Model Mapping Guide - IMO mapping is such a massive
> topic it deserves its own guide. And this is it :) I have put A LOT of
> work into this content, but there is still tons to do.
> a) Chapters I think are in good shape: Data_Categorizations,
> Basic_Types, Composition, Identifiers
> b) Chapters that need some work: Collections,
> c) Chapters that either still need writing or new major work: Entity, Natural_Id,
Associations, Secondary_Tables, Attribute_Access, Mapping_Overrides,
> fragments", Naming_Strategies, SQL_Identifier_Quoting, Database_Constraints,
> This content is in documentation/src/main/docbook/mapping. To build it,
> run `gradle renderDocBook_mapping` and look in
> 3) Hibernate Integrations Guide - This is intended to document all the
> major integration points with Hibernate. So far it is just a chapter on
> Service+Registry. I have started keeping a list of topics to cover in
> Feel free to add your favorites!
> On Thu, Jul 30, 2015 at 2:11 AM Emmanuel Bernard <emmanuel(a)hibernate.org>
>> I think topical guides never got traction because the work on doc was
>> down to zero. I would not give up hope on them :)
>> > On 28 Jul 2015, at 19:51, Steve Ebersole <steve(a)hibernate.org> wrote:
>> > So tentatively I have the following docs:
>> > 1) "User Manual" - mostly done
>> > 2) "Domain Model Mapping Guide" - work in progress, but
>> > 3) "Integrations Guide" - atm this will be just the devguide with
>> > Service+Registry chapter; but I'd like to circle back and pick up other
>> > topics later.
>> > This leaves some open points of discussion. From the proposal itself:
>> > 1) What do we cover in "batching"?
>> > 2) "additionalmodules"? I am inclined to simply drop that one,
>> unless I
>> > here differently that is what will happen.
>> > Emmanuel replied (on irc maybe? I forget where) that he thought topics
>> > such as "Performance Monitoring" and "Best Practices"
ought to be
>> > documents.
>> > He also suggested a chapter on bootstrapping. I totally agree. I
>> > essentially copied the topical guides on bootstrapping as a chapter in
>> > User Guide. But that brings up an interesting point as to the
>> > between topical guides and documentation. When should something go
>> > I almost like to look at the topical guides as a wiki. I don't think
>> > anyone is thrilled with the SBS "wiki" we have access to. I look
>> > as an asciidoctor-based alternative. Of course between SBS, GitHub
>> > topical guides... gets to be a lot of places to look. Initially the
>> > of the topical guides was to break down the massive documentation into
>> > easily digestible chunks. But that never gained traction. Should they
>> > just go away?
>> > On Mon, Jul 27, 2015 at 5:10 PM Steve Ebersole <steve(a)hibernate.org>
>> >> Sanne, yep thats why I sent the second email with a link ;)
>> >> Anyway.. I just pushed some initial work on the manual. Its not
>> >> yet. And I still need to start on the mapping guide. Let me know any
>> >> thoughts y'all have.
>> >> On Mon, Jul 27, 2015 at 2:31 PM Sanne Grinovero
>> >> wrote:
>> >>> I didn't receive an attachment. AFAIK the mailing list drops
>> >>> On 27 Jul 2015 14:39, "Steve Ebersole"
>> >>>> I have been putting a lot of TLC into the ORM documentation
>> >>>> getting ready for 5.0 to go Final. To that end I have put
>> >>>> proposal for these changes, it is attached. I'd like to get
>> >>>> feedback. Thanks
>> >>>> _______________________________________________
>> >>>> hibernate-dev mailing list
>> >>>> hibernate-dev(a)lists.jboss.org
>> >>>> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>> > _______________________________________________
>> > hibernate-dev mailing list
>> > hibernate-dev(a)lists.jboss.org
>> > https://lists.jboss.org/mailman/listinfo/hibernate-dev