db-torque-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "yong LIANG" <yong-liangli...@hotmail.com>
Subject RE: (frustrated torque first timer) Please update the Tutorial
Date Wed, 06 Jul 2005 19:58:30 GMT
Please don't misunderstand me.
I think the tutorial is quite close be being great.
The author picked ONE simple sample application and walked the user through 
each step sticking to his sample app.
That is really great.
It is also great that this sample app is really simple yet still covers most 
stuff.
So the project introduced in the tutorial is great.
And yes, a tutorial is NOT for answering all questions.
That is the job of the user guide (which needs improvement, I think)

BUT while a tutorial is supposed to make ONE sample application work, it 
should explain the necessary steps to do so.

All questions I raised are questions that need to be answered in the 
tutorial as they are required to make the tutorial sample work.

(e.g. the tutorial does not mention anything about the db driver. Yet if you 
dont place that thing at a correct location, the tutorial app does not work. 
So since the tutorial relies on this driver, it needs to mention its use)

Thats what I meant.

So I really dont want to increase the tutorials complexity here. All I want 
is more explanations on the steps needed to make the one simple sample app 
work. (Remember who is the user of the tutorial: newbies. They don't know 
anything about torque. So the tutorial has to be more kindergarten style and 
explain more)

Yong


>From: "Caron, Roger A." <roger.caron@pw.utc.com>
>Reply-To: "Apache Torque Users List" <torque-user@db.apache.org>
>To: "'Apache Torque Users List'" <torque-user@db.apache.org>
>Subject: RE: (frustrated torque first timer) Please update the Tutorial
>Date: Wed, 6 Jul 2005 13:59:45 -0400
>
>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
>separately.
>
>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
>book.
>
>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
>
>tutorial.
>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
>stuff).
>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?
>
>Thanks
>
>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.
>
>Thanks
>
>Yong
>
>_________________________________________________________________
>Take advantage of powerful junk e-mail filters built on patented
>Microsoft(r)
>SmartScreen Technology.
>http://join.msn.com/?pgmarket=en-ca&page=byoa/prem&xAPID=1994&DI=1034&SU=htt
>p://hotmail.com/enca&HL=Market_MSNIS_Taglines
>   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
>

_________________________________________________________________
Take advantage of powerful junk e-mail filters built on patented Microsoft® 
SmartScreen Technology. 
http://join.msn.com/?pgmarket=en-ca&page=byoa/prem&xAPID=1994&DI=1034&SU=http://hotmail.com/enca&HL=Market_MSNIS_Taglines

  Start enjoying all the benefits of MSN® 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


Mime
View raw message