Re: [Hibernate-devel] Documentation in DocBook

[Gavin_King/Cirrus%<CI...@ci...>]

>>- Move chapters and sections around for a more consistent read

>Done. I hope this is an improvement.

I need more time to think some of the reordering through .... the
previous order was designed to get people started as quick as
possible ... topics went from "basic" to "advanced". The new
ordering is much more by subject which makes it more readable
for most users but perhaps harder for brand new users just
getting started. Anyway, I will put some thought into this and
perhaps suggest some further changes.

>I still have some ideas left and
>like to rewrite some chapters (especially the transaction and
>association handling, which seems most confusing for hibernate
>beginners, including myself).

Yeah, spot on.

collections:
Many users seem to have trouble the first time they map an
association. But only ever that first time. That definately
points to problems in the doco.

transactions:
Just recently I've noticed lots of people with problems arising
from forgetting to flush the session when not using the
Transaction API. Also people are uncomfortable calling
Transaction.commit(), Transaction.rollback() when using
container managed transactions. It needs to be clearer that
this doesn't actually call UserTransaction.commit(),
UserTransaction.rollback().

>>- Convert graphics to vector and make a small styleguide for this

>Done. We are using OpenOffice Draw, because it's the only cross
>platform vector drawing tool. Try it, it's not that bad if you know
>how to use it.

cool. unfortunately I'm having trouble checking this stuff out of CVS.
Are you sure you checked in all the binary files with -kb?

>>- Prepare stylesheets for HTML version

>Modified stylesheets. Sorry, I didn't use the hibernate css (blue
>background), because the images are not transparent and I don't have
>time to fix this. It doesn't lock that bad either and could be easily
>changed later.

Its beautiful. The only problem with presentation at the moment is I
think subsection headings are too large. I might be able to fix this
just by fiddling the css. I'll have a look later.

>>- Write makefiles and documentation for automatic output generation

>Still pending because I haven't decided for make or Ant.

I would very much prefer Ant if its at all possible. I've finally
started using the ant build script to generate javadoc, etc, So
it would be really nice to integrate this stuff with the existing
stuff. My dream is to eventually be able to do a whole release
with just a single Ant task but I'm not there yet ;)

>>- Checkin to CVS

>Done, with a lot of cursing about CVS over ssh. I cannot use any
>graphical client with Unix... any solution for this problem?

In my experience the graphical clients are really not worth
the effort. I just use the cmd-line client under win2k, even
though I _could_ use winCVS.

>So, if everyone agrees that the new documentation can replace the old
>"Programming Guide", the following steps would be neccessary:

yes, I would like to do this stuff for 1.0.2 if possible, since I want
to document the new 1.0.2 features in docbook. Could you tell me
exactly how up to date the docbook text is compared to the aft text? I
did make a couple of minor changes this week and I might need to copy
them over.

>Thats it. Hm, the "Toolset Guide" could be integrated as a separate
>chapter?

yep. And we should probably move the documentation of Dialects
somewhere else, since they are no longer used only by the schema
generator, as was originally the case.

>The website itself could do with little reorg, too. I think the
>whole Q&A and feature list is really one big block itself.

The website could do with many improvements actually.....

Thanks for all this Christian, its awesome.