[hibernate-dev] ORM Documentation

[Steve Ebersole]

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 <steve at 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 <steve at 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 <emmanuel at 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 <steve at 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 <steve at 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 <sanne at hibernate.org>
>>> >> wrote:
>>> >>
>>> >>> I didn't receive an attachment. AFAIK the mailing list drops them?
>>> >>> On 27 Jul 2015 14:39, "Steve Ebersole" <steve at 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 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
>>>
>>>