db-torque-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Caron, Roger A." <roger.ca...@pw.utc.com>
Subject RE: (frustrated torque first timer) Please update the Tutorial
Date Wed, 06 Jul 2005 17:59:45 GMT
The goal of any tutorial is to provide high level setup and usage
information.  You will rarely find a detailed tutorial answering all
questions imaginable.  In any tutorial, some assumptions are made about the
skill level and experience of the users.  The Torque tutorial is no
different.  If the tutorial is cluttered with the specifics and definitions
about every component of Torque, how to configure your environment, how to
set it up and run it, including the differences between one DBMS and
another, the turorial would take hours to read and would leave the
first-time user feeling like they've gotten too much useless information.  I
only like to see the solution for a problem after I've seen the problem.
While the tutorial could answer some more common questions, the tutorial is
not the place to answer all of these questions.  This is why this message
board and others like it are such good resources.

Imagine a tutorial teaching someone how to drive a car.  To answer all
possible questions, the tutorial would read something like this:

"Be sure the driver's door is unlocked and open it.  The driver's door is a
cutout in the frame of an automobile providing easy access for the driver to
enter and exit the automobile.  This cutout is filled with a separate framed
assembly covered with sheetmetal to protect the driver from outside
disturbances.  Identify the door and attempt to open it by pulling on the
door handle.  The door handle is connected to a release mechanism which
allows the door to swing open and keeps the door closed when locked.  If the
door is indeed locked, locate the key and attempt to unlock the door.  A
door lock is used to prevent unauthorized entry into the vehicle.
Authorization is granted through the key, a metal object which is shaped to
uniquely fit the lock mechanism inside your door.  Use the key to unlock the
door by inserting it into the keyhole and turning it counter clockwise until
the door unlocks.  Pull the release latch to open the door...."

As you can see, answering all possible questions in a tutorial can clutter
up the tutorial and the user would likely skip 75% of the tutorial and
simply skip to the part they're looking for, and not learn all the basic
concepts leading up.  In my example above, a user simply wants to learn how
to drive a car, but would likely only find the specifics relating to their
question somewhere on page 96.  They're better off learning the basics of
driving a car at a high level, and then learning the details at a later
time, or posting questions to their driver's ed instructor or someone with
more experience (perhaps through a mailing list...).  A tutorial is not
intended to be a complete set of setup instructions to get you fully running
"In 10 minutes or less."

Hopefully someone on this board will read your questions and post responses

If this post is off-base, rude, or comes off as being abrasive, that was not
my intention.  I simply wanted to demonstrate how tutorials can often be
relied on too heavily.  A few minutes browsing the archives can save you
hours of hair pulling.  The tutorial is not the answer book; it's simply a
guide, similar to the difference between Cliff Notes and reading the actual

Good luck in learning the answers to your questions.

Roger Caron

-----Original Message-----
From: yong LIANG [mailto:yong-liangliang@hotmail.com]
Sent: Wednesday, July 06, 2005 1:16 PM
To: torque-user@db.apache.org
Subject: (frustrated torque first timer) Please update the Tutorial

As a first time user of torque I am a little bit frustrated with the 
tutorial you provided as it does not answer all questions (in my opinion). 
Find those questions below. I'd really appreciate it if you could update the

In my opinion, there needs to be a tutorial (step by step, every single 
thing explained, for newbies) and a user guide (explaining all features and 
So the tutorial can't assume that the user knows much.

Here are those questions:

1. What is this Torque Runtime Properties thing you talk about? I have no 
idea what that means or if I am supposed to do anything in this step.

2. If I unpack torque-3.1.1.zip, I do NOT see the directory structure that 
you mentioned. Why not?

3. Exactly which files do I need? (At first you only talk about the two 
Torque jars, but later you talk about dependencies)

4. Where do I get those files?

5. Where exactly (directory) do I put each of those files?

6. How do I handle those files? (E.g. which one has to be in my classpath? 
Do I only need to add the directory to the classpath or each and every 
single jar? Istn't there a better way than the classpath?)

7. Where do I put the database driver? (Someone in this mailing list says it

has to be in %MAVEN_HOME%/lib/endorsed. If that is correct, why does the 
tutorial not mention that? If there is a better location for that file, why 
does the tutorial not talk about that?

8. Why does it not work to create/drop a database or tables in PostgreSQL 
even if everything is set up correctly? Why do some on this list suggest to 
use the SQL scripts manually instead of letting maven do that? Isn't that a 
bug/problem in torque or maven?

9. Why does the tutorial not mention this issue?

10. If 'maven torque' works and I create the database manually and I create 
the Bookstore.java application - what could be the reason that I get the 
message "No java files to be compiled" and then BUILD SUCCESSFUL? This 
process does not produce ANY class files anywhere. What did I do wrong?


Sorry for the frustrated voice in my mail. I didn't mean to insult anyone.
Please consider updating your tutorial quickly. That shouldn't take much 
time, I think, as I believe all of those questions can be answered by an 
experienced torque expert without thinking.



Take advantage of powerful junk e-mail filters built on patented
SmartScreen Technology. 
  Start enjoying all the benefits of MSN(r) Premium right now and get the 
first two months FREE*.

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

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

View raw message