db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From M Flood <mdfl...@starpower.net>
Subject A Torque book?
Date Sun, 13 Feb 2005 14:15:16 GMT
Thomas:

You have set your priorities, which is certainly fair.

But please consider again the benefits of traditional publication (beyond merely 
the royalty income):

1.  Marketing image of the significance of Torque.  SourceForge is full of 
database tools, and some of them are even very good.  But the commitment of a 
third-party publisher to invest their effort and reputation in a book would 
signal to outsiders that Torque is a serious effort worthy of serious 
consideration.  You know Torque is serious; after lots of self-teaching, I know 
it's serious; but the average newcomer does not.

2.  Editors and proofreaders.  A professional editor will enforce rules for 
comprehensiveness and internal consistency of the content.  Unfortunately, this 
has been an issue for Torque in the past.  Isn't this precisely the area where 
you would like some additional help?

3.  Sales force and marketing presence.  Manning or O'Reilly will make thousands 
of new developers aware of Torque.  (I suspect I am a typical case:  O'Reilly, 
Manning, etc., are one of the first places I look when I am vetting a new 
technology or looking for technical advice.)  Developer eyeballs are the life 
force of a successful open-source project, and this is a great way to attract 
them.

And then there's the cash, of course...

Best -- Mark






Response to: A Torque book? (M Flood)

Subject: A Torque book?
From: thomas fischer <Fischer@seitenbau.net>
Date: Mon, 7 Feb 2005 09:11:00 +0100
Content-type: text/plain; charset=US-ASCII






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 <mdflood@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




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


Mime
View raw message