6:55 p.m.
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>
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> 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>
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>
>> 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>
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