DO NOT REPLY TO THIS EMAIL, BUT PLEASE POST YOUR BUG� RELATED COMMENTS THROUGH THE WEB INTERFACE AVAILABLE AT <http://issues.apache.org/bugzilla/show_bug.cgi?id=34557>. ANY REPLY MADE TO THIS MESSAGE WILL NOT BE COLLECTED AND� INSERTED IN THE BUG DATABASE.
http://issues.apache.org/bugzilla/show_bug.cgi?id=34557 ------- Additional Comments From [EMAIL PROTECTED] 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 websites. - 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: http://issues.apache.org/bugzilla/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the assignee for the bug, or are watching the assignee.
