cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject DO NOT REPLY [Bug 34557] - This tutorial sucks.
Date Fri, 22 Apr 2005 21:50:13 GMT

------- Additional Comments From  2005-04-22 23:50 -------
(In reply to comment #1)
> Thanks for reporting this. 
> If you want this tutorial to become usable, you need to  tell what is wrong.
> Would you mind to list your reasons of why this tutorial is not usable?

I've listed a few so far, but I'll spend this note going back over the tutorial
quickly and give you an actuall bulleted list of my concerns, at least the ones
I remember:

- Under Introduction, last paragraph.  You mention it comes from the "tutorial",
but no mention of what path that is located under.  It would be also a good idea
to give a url or at least a guide as to where that tutorial lived under default

- The SQL code list does not conform to Postgres SQL syntax (the DB I happen to
have installed).  I don't know what particular flavor of SQL this is, but it
should be noted as part of the listing.

- Diving In.  This section mentions a sitemap.  First, that path and full
filename (something/something/sitemap.xmap) was not listed.  Second, it says to
clear everything out of -<map:pipelines>-, but then says to add an entry in the
same location; but the entry is of -<map:pipeline>- (singular).  This is
confusing, because the actual tutorial directory's current sitemap has much more
than just a single pipeline section in it, so do we clear that out? 
Additionally, was that a type-o?  Should I put this listed code -inside- of
pipelines, or delete the pipelines section and replace it with this code?  Or
perhaps I should rename the pipeline in the code to pipelines, and use that? 
You should just say, please look at the sitemap.xmap file in something/something
path, and then say this is the part of the file we are interested in right now.

- To add to the confusion, most (all?) of the listings here are out of date and
do not match the files actually found in the tutorial directory.  (Which led me,
along with the fact its not in samples/, it's in samples/db/somesuch/someother/
directory, to believe that the tutorial directory I did find was not the
directory I was to use, but rather I should create a new directory and create
new files there -- which lead to many other problems, since I wasn't sure what
was needed or not to be copied from the various samples available).

- Again, in diving in, the listing does not match the description.  The
description say that we are telling cocoon that we are mapping urls with xml to
the directory doc/.  Well, you -are-, but your listing has 8 other things it's
doing too.  Just list what we are talking about -right now-.   If you want to
have a large section of the file, make it a separate document and link to it, or
something.  Keep the tutorial free of long listings, please, and also, to repeat
myself, keep them up to date!  I mean, this is a new frame work to make things
easy, so it should be 'easy' to at the least have a link to the original file,
if not be able to have the original and the listing be in sync.

- Creating the Pages:  This section, it's really confusing.  In the last section
I was supposed to perform a labatomy on some file I had to go find and hope that
I found the correct one.  This section, what was I supposed to do?  This listing
also doesn't match what's in the tutorial.  It also doesn't say that at this
point I should point my browser at home.xml, even though it suggest that when I
look at home.html, I'll notice it's quite different!

- Our first form.  Either do it right the first time, or -breifly- mention that
you should check out such and such chapter for more maintainable methods of
accessing a database.  The current first two paragraphs would be best deleted.

This about where I gave up, the descriptions of what was going on were poor, the
listings still didn't match up.  I was tryng to make my own copy work by
selectively copying the files out of the original tutorial directory.  I
couldn't get the bindings to work (no doubt because I had no idea how to
auth/connect to my database).  On the whole I was extremely dissatisfied with
this document.  It read -ok-, if you don't try to perform anything it suggests.
 But it was extremely poor and being clear, to the point, and accurate for
someone trying to follow along.  I understand that documentation is a costly
thing, and rather hard to get.  But at the same time it is rather vital to a
project this size!  Please please, re-evaluate your software.  Just keep in mind
that you mother may have to do it, and explain things as such.  (Just assume she
knows all the definitions to words and concepts that are common to other
computer science/engineering areas).  I appreciate also the person or persons
that made the original document, and this is not an attact on them.  But I do
not think this tutorial is acceptable the way it is now.

Thanks for your time, and I hope my critiques have helped.

Configure bugmail:
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

View raw message