db-torque-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thomas Fischer <fisc...@seitenbau.net>
Subject RE: (frustrated torque first timer) Please update the Tutorial
Date Fri, 08 Jul 2005 09:41:08 GMT





Hi,

ok, let's give it a try. I will look over it from the point of view of an
developer, maybe Scott also wants to do that. I can also commit the final
version. But please do not be offended if your changes do not go in 1:1.

To create an updated version of the tutorials, do the following
- checkout db-torque from cvs
- install and setup maven (probably you have already done that)
- change into the db-torque directory
- the xdoc sources of the tutorail are in xdocs/tutorial. Edit these files.
- use the command
maven xdoc
to build the html pages. The generated pages can be found in the
target/docs subdirectory.

If you are finished and want to share your changes:
- create an account in scarab (http://issues.apache.org/scarab/issues)
- request a role as developer in Torque > documentation
- create an issue in the module Torque > documentation
- upload the changed files (preferably with diff -u)
- save the issues

If you have any questions, please feel free to ask me

   Thomas



"Brent Atkins" <Brent.Atkins@pro-sys.biz> schrieb am 06.07.2005 22:26:10:

> I'm in agreement with what most of you have said.  I agree that the
sample
> app in the tutorial is really good, and I wouldn't change it even if I
> weren't so lazy.
>
> To me the biggest kicker for it seems to be the amount of knowledge that
a
> person has to have in order to accurately use the tutorial.  By no means
do
> I want to disparage the great work done by stephenh, mpoeschl, seade,
> quintonm, dlr, or Thomas - but I do want to tweak a few things here and
> there in Step 1 and Step 2 - plus a couple of very minor tweaks in Step
3.
> I'll make the changes and post them somewhere (is here the best place or
> should I email directly to a submitter?).
>
> So rest assured I am not planning on rewriting the whole thing from
scratch.
> It's too good to toss, and I'm much too lazy to do that anyway.  I just
plan
> on massaging it here and there until even a dope like me can understand
it.
> If you like it, wonderful.  If you don't it's not gonna make me cry.
Well,
> only a little... :)
>
> If someone can tell me what the conceptual difference between a Tutorial
and
> a User Guide is, I'll be happy to take a look at it too.
>
> (Did I really just volunteer to do all of this?  My wife is gonna kill
> me...)
>
> -----Original Message-----
> From: Matthias Klein [mailto:matthias@cmklein.de]
> Sent: Wednesday, July 06, 2005 4:05 PM
> To: 'Apache Torque Users List'
> Subject: RE: (frustrated torque first timer) Please update the Tutorial
>
> I agree that the tutorial right now is quite good already.
> However, as a torque newbie I ran across most of the issues that Yong
> mentioned as well. (I even asked for help about one of the issues and got
an
> immediate and very helpful response. Thanks!) So if someone is willing to
do
> some work on the tutorial I suggest simply stick with the example
> application introduced there and just "streamline"
> the instructions:
> - Relocate some additional information (like: click here if you want to
know
> more about this)
> - Add some more instructions on certain issues (see posting of Yong)
> - Make the tutorial more a whole thing again (one can see that it has a
> great core yet has been patched a bit too often)
>
> But over all: the tutorial including the sample application is almost
great.
> I believe it does not take too much work to make it really super.
>
> Matt
>
>
> > -----Original Message-----
> > From: Thomas Fischer [mailto:tfischer@apache.org]
> > Sent: Wednesday, July 06, 2005 4:25 PM
> > To: Apache Torque Users List
> > Subject: Re: (frustrated torque first timer) Please update the
> > Tutorial
> >
> > Hi,
> >
> > We do have a problem with documentation in Toque, I agree to that. In
> > my opinion, however, the tutorial is not the problem (although there
> > might be a few unclear points). The real problem is the very patchy
> > users guide.
> >
> > I remember I have tried to follow the tutorial when Torque
> > 3.1.1 was released, and I did not have a problem to get the sample
> > application running, when I followed exactly the steps outlined in the
> > tutorial. The problems uually arise when one plays around a bit (to
> > learn more about the framework), and one inserts some errors which are
> > not easy to notice.
> >
> > However, when I tried to follow the tutorial, I did not start from the
> > very beginning, which made things easier. I remember it was a hassle
> > setting up maven, and maybe I already had the driver at the right
> > place.
> >
> > When releasing Torque 3.1.1, the tutorial was improved very much from
> > the
> > 3.1 version. I still remember the wekly posts on the mailing lists
> > about the errors in the tutorial; they have reduced to about two posts
> > in half a year after 3.1.1. From that I conclude that the tutorial is
> > quite ok now.
> >
> > Yong, thanks for noting some of the weak points in the tutorial. I
> > will look at the point you critisize and see how it can be improved.
> > There is just one thing I can answer without some research: the
> > postgresql create-db task is not working in all circumstances (no idea
> > whether it works in any circumstances at all), but creating the db
> > manually is fine.
> > In some databases (e.g. oracle) Torque does not even try to create the
> > db.
> > I will add a remark on that.
> >
> > Brent, I appreciate very much you willing to rewrite the tutorial. But
> > (as you might have noticed) I am of the opinion that the Tutorial as
> > it is now is far too good to be simply thrown away. However, if you
> > have ideas of particular points that can be improved, I'll be glad to
> > hear them.
> >
> > Bill, some plans exist to release Torque 3.2 in the not-so-far future.
> > It will contain the ant build scripts again as an alternative to
> > maven.
> > However, I am unsure whether this should be put into the tutorial at
> > all.
> > Maybe there should be two tutorials, one for ant and one for maven.
> > But this is not thought to the end yet.
> >
> > All I have written here is my own personal opinion, I hope nobody
> > feels offended. If you disagre with me, I'd be happy to hear about it
> > on the users mailing list.
> >
> >         Thomas
> >
> >
> > ---------------------------------------------------------------------
> > 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
>
>
>
>
> ---------------------------------------------------------------------
> 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


Mime
View raw message