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 imagine, as a user, that would get old after a while - not being able to just click there. Opinions?
On Mon, Aug 3, 2015 at 7:15 PM Steve Ebersole <st...@hibernate.org> wrote: > 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 <st...@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 >> 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 <emman...@hibernate.org> >> 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 <st...@hibernate.org> 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 <st...@hibernate.org> >>> 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 <sa...@hibernate.org> >>> >> wrote: >>> >> >>> >>> I didn't receive an attachment. AFAIK the mailing list drops them? >>> >>> On 27 Jul 2015 14:39, "Steve Ebersole" <st...@hibernate.org> 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@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 >>> >>> _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
