A Torque book?

[M Flood <md...@starpower.net>]

Greetings all:

I am someone who's struggled through to a basic understanding of 
Torque.  I love the thing.  But the documentation?  Oy. 

Has any thought been given to a more cohesive and comprehensive 
reference -- e.g., an O'Reilly <http://www.oreilly.com/> "Apache 
Torque:  The Definitive Guide", or a Manning <http://www.manning.com/> 
"Apache Torque in Action"?  The pieces are mostly there already, on the 
Torque site, the wiki, and the forums, but:  (a) there are significant 
differences across versions, and the online docs do not always stay in 
sync with the app; (b) users are required to google several places and 
assess the credibility/relevance of discussions to assemble an answer to 
questions; and (c) there is a lack of consistent format to guide the 
learning process.

I really think improved documentation would open up widespread 
acceptance of Torque.  Please give it some thought.  I don't see any 
other open-source java O/R layers that give me the kind of flexibility 
that Torque does, in the sense that the database design can remain fully 
decoupled from the object model.  That makes it architecturally superior 
to Hibernate, JDO, Castor, etc., (IMHO). 

Thanks -- Mark Flood

---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org

RE: A Torque book?

[Thomas Fischer <Fi...@seitenbau.net>]

Hi,

you touch a sore point here. You are right, the Torque documentation is
quite rudimentary.

What I say in the following is extrapolated from my own position, so it
might not be true for the other committers (though I suspect their position
is pretty much the same)
 I am quite busy in my daytime job. I am not ready to spend most of my
spare time to Torque, so there is not much time left. This slot has to be
divided into
a) improvements in the code
b) bug fixing and testing
c) stuff like cvs organisation, creating releases
d) answering questions on the mailing list
e) documentation
Of these tasks, writing documentation seems the least urgent and brings the
least gain to the author himself (he already knows what he is writing
about), so documentation has been neglected in the past. Also, writing good
documentation is really time-consuming.

Despite that, in my opinion the documentation is in the process of getting
better at the moment (although its a slow process):
- Scott has fixed the tutorial so it works again in Torque-3.1
- The new features which have been introduced since 3.1.1 in CVS have been
documented by the respective authors.

As to writing a book, this might be a good idea of how to get to a better
documentation. In my opinion, the advantage of a book vs online
documentation is that the author can make some money with the book. This is
a good thing in my opinion, because it increases the chance of a book being
written. For myself, though, I do not need additional money so badly, so my
personal efforts in improving the documentation will go into the online
documentation, not into a book. If, however, somebody else would write a
book about Torque, I would support it.

To advertise the online documentation a bit: If somebody is ready to write
up or improve parts of the documentation, I will be quite happy to look
through it and commit it. Also, people can contribute to the documentation
is the wiki.

    Thomas

M Flood <md...@starpower.net> schrieb am 06.02.2005 14:36:06:

> Greetings all:
>
> I am someone who's struggled through to a basic understanding of
> Torque.  I love the thing.  But the documentation?  Oy.
>
> Has any thought been given to a more cohesive and comprehensive
> reference -- e.g., an O'Reilly <http://www.oreilly.com/> "Apache
> Torque:  The Definitive Guide", or a Manning <http://www.manning.com/>
> "Apache Torque in Action"?  The pieces are mostly there already, on the
> Torque site, the wiki, and the forums, but:  (a) there are significant
> differences across versions, and the online docs do not always stay in
> sync with the app; (b) users are required to google several places and
> assess the credibility/relevance of discussions to assemble an answer to
> questions; and (c) there is a lack of consistent format to guide the
> learning process.
>
> I really think improved documentation would open up widespread
> acceptance of Torque.  Please give it some thought.  I don't see any
> other open-source java O/R layers that give me the kind of flexibility
> that Torque does, in the sense that the database design can remain fully
> decoupled from the object model.  That makes it architecturally superior
> to Hibernate, JDO, Castor, etc., (IMHO).
>
> Thanks -- Mark Flood
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
> For additional commands, e-mail: torque-dev-help@db.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org