I have been putting a lot of TLC into the ORM documentation this weekend getting ready for 5.0 to go Final. To that end I have put together a proposal for these changes, it is attached. I'd like to get some feedback. Thanks _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

Sanne, yep thats why I sent the second email with a link ;) Anyway.. I just pushed some initial work on the manual. Its not complete 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 <sanne(a)hibernate.org&gt; wrote: > I didn't receive an attachment. AFAIK the mailing list drops them? > On 27 Jul 2015 14:39, "Steve Ebersole" <steve(a)hibernate.org&gt; wrote: > >> I have been putting a lot of TLC into the ORM documentation this weekend >> getting ready for 5.0 to go Final. To that end I have put together a >> proposal for these changes, it is attached. I'd like to get some >> feedback. Thanks >> >> _______________________________________________ >> hibernate-dev mailing list >> hibernate-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> >

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&gt; wrote: > > So tentatively I have the following docs: > > 1) "User Manual" - mostly done > 2) "Domain Model Mapping Guide" - work in progress, but progressing nicely. > 3) "Integrations Guide" - atm this will be just the devguide with the > 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, so 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 separate > documents. > > He also suggested a chapter on bootstrapping. I totally agree. I > essentially copied the topical guides on bootstrapping as a chapter in the > User Guide. But that brings up an interesting point as to the distinction > between topical guides and documentation. When should something go where? > 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 at this > as an asciidoctor-based alternative. Of course between SBS, GitHub wiki, > topical guides... gets to be a lot of places to look. Initially the idea > of the topical guides was to break down the massive documentation into more > 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&gt; wrote: > >> Sanne, yep thats why I sent the second email with a link ;) >> >> Anyway.. I just pushed some initial work on the manual. Its not complete >> 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 <sanne(a)hibernate.org&gt; >> wrote: >> >>> I didn't receive an attachment. AFAIK the mailing list drops them? >>> On 27 Jul 2015 14:39, "Steve Ebersole" <steve(a)hibernate.org&gt; wrote: >>> >>>> I have been putting a lot of TLC into the ORM documentation this weekend >>>> getting ready for 5.0 to go Final. To that end I have put together a >>>> proposal for these changes, it is attached. I'd like to get some >>>> 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

Well Identifiers in the mapping guide still needs some work. I guess move 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&gt; 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 > documentation/target/docbook/publish/manual. > > > 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, Generated_attributes, > "read/write > fragments", Naming_Strategies, SQL_Identifier_Quoting, Database_Constraints, Auxiliary_DB_Objects > > This content is in documentation/src/main/docbook/mapping. To build it, > run `gradle renderDocBook_mapping` and look in > documentation/target/docbook/publish/mapping. > > > 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 Hibernate_Integrations.xml. > Feel free to add your favorites! > > > On Thu, Jul 30, 2015 at 2:11 AM Emmanuel Bernard <emmanuel(a)hibernate.org&gt; > wrote: > >> 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&gt; wrote: >> > >> > So tentatively I have the following docs: >> > >> > 1) "User Manual" - mostly done >> > 2) "Domain Model Mapping Guide" - work in progress, but progressing >> nicely. >> > 3) "Integrations Guide" - atm this will be just the devguide with the >> > 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, so >> 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 >> separate >> > documents. >> > >> > He also suggested a chapter on bootstrapping. I totally agree. I >> > essentially copied the topical guides on bootstrapping as a chapter in >> the >> > User Guide. But that brings up an interesting point as to the >> distinction >> > between topical guides and documentation. When should something go >> where? >> > 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 at >> this >> > as an asciidoctor-based alternative. Of course between SBS, GitHub >> wiki, >> > topical guides... gets to be a lot of places to look. Initially the >> idea >> > of the topical guides was to break down the massive documentation into >> more >> > 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&gt; >> wrote: >> > >> >> Sanne, yep thats why I sent the second email with a link ;) >> >> >> >> Anyway.. I just pushed some initial work on the manual. Its not >> complete >> >> 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 <sanne(a)hibernate.org&gt; >> >> wrote: >> >> >> >>> I didn't receive an attachment. AFAIK the mailing list drops them? >> >>> On 27 Jul 2015 14:39, "Steve Ebersole" <steve(a)hibernate.org&gt; wrote: >> >>> >> >>>> I have been putting a lot of TLC into the ORM documentation this >> weekend >> >>>> getting ready for 5.0 to go Final. To that end I have put together >> a >> >>>> proposal for these changes, it is attached. I'd like to get some >> >>>> 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 >> >>