I thought this forward would be of interest to the DC folks and the community at large. -jfarr
Zope has some of the worst documentation I have ever encountered. I paged through it for a while and was unable to get to any actual information, just marketing-esque hype. I turned the investigation over to my typically very fast research guy, figuring maybe I just had the wrong set of docs or something; after learning Python and spending several solid weeks of trying to figure out how to get it to update objects in Oracle (vs. just view them), he gave up on it; we aren't going to use it.
It's a good idea, and I hear only good things about Python, but Zope is Just Not There Yet.
YMMV, Brenda
Ouch. That hurts. Where was this taken from? Jonothan Farr wrote:
I thought this forward would be of interest to the DC folks and the community at large.
-jfarr
Zope has some of the worst documentation I have ever encountered. I paged through it for a while and was unable to get to any actual
<snip> -- Chris McDonough Digital Creations, Inc. Zope - http://www.zope.org
Zope has some of the worst documentation I have ever encountered. I paged through it for a while and was unable to get to any actual <snip>
Ouch. That hurts.
While it hurts, it's not far from the truth. Have you considered putting a guy/gal on documentation exclusively? In the projects I have encountered in real life (if I can be said to have such a thing ;), I've found this provides the most consistent and best documentation. A person who's only job is to interact with the staff and provide legible information on what they produce is a godsend. I know it costs money, but your product really deserves it. Just a recommendation on which order one should go through the docs would go a long way. Alexander Limi (who will stop whining, and start learning :) http://mp3.no
[snip]
While it hurts, it's not far from the truth. Have you considered putting a guy/gal on documentation exclusively? In the projects I have encountered in real life (if I can be said to have such a thing ;), I've found this provides the most consistent and best documentation. A person who's only job is to interact with the staff and provide legible information on what they produce is a godsend.
I know it costs money, but your product really deserves it.
As a matter of practical interest - how much would it cost to hire someone, and for how long to improve the Zope docs to the next user-friendly level? What is the real demand now for this? How many here would be willing to contribute [how_much] towards this? Zope is free, but I for one don't mind paying some money to save time and sanity, and improve the likelihood of this technology growing well. Zope's sophistication means that it gets used and abused in so many ways, that docs may have a hard time keeping up. Yet even a focused trawl thought the mail digest would be huge plus. Just organizing the known wisdom. This has been done in David Beazley's 'Python Essential Reference'. I just received it yesterday - It's lovely, clean, small, handy and I learnt a lot in a few hours already :-) It is a godsend to have a small paperback like this with clear formatting and typography.. long live good books! [nice cover too - Mayan temple] Perhaps it is still too soon for Zope - perhaps not. I hope the recent announcements by DC mean that much better docs will be forthcoming soon.. thoughts? - Jason
On 12/10/99 8:06 AM, Jason Cunliffe at jasonic@nomadicsltd.com wrote:
[snip]
While it hurts, it's not far from the truth. Have you considered putting a guy/gal on documentation exclusively? In the projects I have encountered in real life (if I can be said to have such a thing ;), I've found this provides the most consistent and best documentation. A person who's only job is to interact with the staff and provide legible information on what they produce is a godsend.
I know it costs money, but your product really deserves it.
As a matter of practical interest - how much would it cost to hire someone, and for how long to improve the Zope docs to the next user-friendly level?
We do have someone hired purely as a tech writer, but we also have to have the material to do the work with, and most of our people are working on other "paying" projects. In the end the company does have to flow cash. The ZDP project has been doing an admirable effort at attempting to get more documentation written, but the job is not as easy as it looks at the outset. Writing good documentation is not easy. Witness most products. While the documentation of Zope is not great, I'd take offense that it's the "worst" on the market. You've obviously not experienced the problems of voluminous documentation that is simply wrong, for the wrong version, or unindexed. 10,000 pages without an index is less useful than 1000 with.
What is the real demand now for this? How many here would be willing to contribute [how_much] towards this?
This needs to move to the ZDP list.
Perhaps it is still too soon for Zope - perhaps not. I hope the recent announcements by DC mean that much better docs will be forthcoming soon..
We're working on it, but remember this is an OPEN SOURCE project, which means that the community is encouraged to participate. If you dislike a section of documentation, you need to be specific in what you need documented past "It sucks", exact examples you think would help, etc. Chris -- | Christopher Petrilli Python Powered Digital Creations, Inc. | petrilli@digicool.com http://www.digicool.com
At 09:10 10/12/99 -0500, Christopher Petrilli wrote:
We do have someone hired purely as a tech writer, but we also have to have the material to do the work with, and most of our people are working on other "paying" projects. In the end the company does have to flow cash. The ZDP project has been doing an admirable effort at attempting to get more documentation written, but the job is not as easy as it looks at the outset. Writing good documentation is not easy. Witness most products.
While the documentation of Zope is not great, I'd take offense that it's the "worst" on the market. You've obviously not experienced the problems of voluminous documentation that is simply wrong, for the wrong version, or unindexed. 10,000 pages without an index is less useful than 1000 with.
#1 Please_ don't misunderstand me. I am not bitching, and I personally do not consider Zope "worst" in any sense. On the contrary it is IMHO one of the "best" things happening at the moment. It is partly because of he intense activity here that it is so hard to keep up. I look way for few days to do =other work and hardly know how to begin again. Voluminous documentation that is wrong -- arghh yes - look at computer book publishing now. telephone books of in_from_ation but not well structured, little context, overview, etc. It is rare to find concise works. And they do take a long time and a lot of work to get there. Even 'normal' illustrated books represent a huge amount of effort by many people.. good ones take even longer and cost way more to do well. I know; years ago I worked in fine art book design and production. But when people say - its not easy, not enough, time, people or money..I simply asking Q1: How much time, people, money [quantify] do you think it needs to do Zope docs _well_? Q2: How many on this list are willing to pay $n, and if so how would/could that help? Not a criticism - just trying to see what the scale of the problem or solution is
We're working on it, but remember this is an OPEN SOURCE project, which means that the community is encouraged to participate. If you dislike a section of documentation, you need to be specific in what you need documented past "It sucks", exact examples you think would help, etc.
Yes. Yes. OpenSource and openReSource. It does not 'suck'. It is huge and complex. Good examples are as useful as not. I pointed to the new 'Python Essential Reference, because that IMHO is a pretty good close example to review... as are many (but_not_all_ OReilly In-a-Nutshell editions. And some WROX books. Back when people were bouncing around ideas for improving the zope.org website I suggested a schematic 'map' of Zope with a poster version. Anyone like to see this? What should it contain? When you explain Zope to someone over lunch, what do you draw on that napkin to help? What is the sketch/structure which shows the relationships between hierarchical path inheritance and acquisition? I would be more than willing to help build such a map and am asking for some feedback from people here. so I can help.. ideas? - Jason
Ok, that's it. Two points (ok I'm grumpy tonight) 1) I can't believe docs are really an issue with anyone. <whining mode> Let me take myself as an example (yes this is whining!). I have squeezed out three drafts of a chapter for ZBook called changing context in Zope. They were almost completely made up of examples. I got exactly one (1) response to the first draft from anyone either on the ZDP list or elsewhere (thanks Patrick). Now, it may well be they are completely worthless or off target, but then please say so, so I can save myself the trouble. Say anything. I asked for feedback repeatedly. It is not exactly motivating to write documentation if there is no feedback at all. That makes it appear as though there is no need for documentation - or did I get this wrong. This also what Open Source is about as far as I'm concerned- _co_ operation</whining mode> Moreover, there still is no real policy of DC towards the ZDP documentation. We asked for that repeatedly on the list. For want of a reply, the ZDP group assumed we would have to write everything ourselves as if there were no documentation effort by DC. Do we have to conclude from this that documentation is not their agenda? 2) The existing documents are not exactly good. But I'm no programmer by trade or by education, in fact I'm from a humanities background. Nevertheless, I picked Zope up in about a month or so after it first came out (ok I did have Python experience, but documentation then was worse than now and there was hardly any assistence available like the list does provides). Now, this either means that I am very smart (compliments accepted) or people who claim to have years of computer science background and are able pick up all sorts of other things are doing something very wrong Ah, that feels better provocative-on-purposely-yours Rik
On 12/10/99 3:26 PM, Rik Hoekstra at hoekstra@fsw.leidenuniv.nl wrote:
Moreover, there still is no real policy of DC towards the ZDP documentation. We asked for that repeatedly on the list. For want of a reply, the ZDP group assumed we would have to write everything ourselves as if there were no documentation effort by DC. Do we have to conclude from this that documentation is not their agenda?
I'll let Paul, Amos and Pam talk more specifically, but I think part of it is that we have very different tool sets from everyone else---we use Framemaker. So we're working to try and fix that process so that we can open up documentation to be more collaborative. We could put the Frame documents out there, but how many people have Frame? I thought so. And from the amount that Paul/Amos talk about the ZDP, I am suspect that you've never gotten a single response, etc. If so, then there's something amiss. Chris -- | Christopher Petrilli Python Powered Digital Creations, Inc. | petrilli@digicool.com http://www.digicool.com
[Alexander Limi, on Fri, 10 Dec 1999] :: Just a recommendation on which order one should go through the docs would go a :: long way. Great idea. You know how the Open Source world works, right? This means you just volunteered for the job. :-) The Zope Documentation Project could definitely use more volunteers -- especially among people who are already Zope-proficient. If everyone does just a little bit, it will get better really fast. You can sign up at zdp.zope.org.
Ouch. That hurts.
Where was this taken from?
It would be pretty difficult to explain the purpose of the mailing list I took that message from. Suffice it to say that most of the members are computer professionals. I disagree that the person who posted it has, "very little computer experience." Perhaps not much experience working with relatively immature open source software projects. I don't think they understood what an important resource the community is for finding information. My reason for posting this is what I said in the subject, a reality check. I love the enthusiasm that the Zope community has in general. But I think that the Zope community is largely made up of individuals who already really love Zope. I wanted to present the viewpoint of someone who has no bias for or against Python or Zope. I wanted to present an evaluation solely on the merits of whether it could get their job done. I wanted to point out what those people say Zope needs to have in order to win them over. If you imply that they are not experienced enough or intelligent enough or open-minded enough to use Zope then you are missing the point. Zope is a tool for web programmers, not Python programmers. It has to be useful to them if it is going to be successful. -jfarr
Jonothan Farr wrote:
Ouch. That hurts.
Where was this taken from?
It would be pretty difficult to explain the purpose of the mailing list I took that message from. Suffice it to say that most of the members are computer professionals.
Salesmen ? ;)
I disagree that the person who posted it has, "very little computer experience."
But has this "computer professional" any database (specifically SQL) experience? Were his problems with _using_ zope to do an INSERT INTO or where they in getting the Oracle DA to work (eiher for a "relatively immature" or some "more mature" release of Oracle). Or was he incapable of determining which was the case - perhaps trying to insert into Oracle using the built-in Gadfly adapter ?
From your description it seems to be not the quality of docs (which do need improving), but something more fundamental, like reading the wrong docs, knowing nothing of databases or just not trying and lying to you that he did.
Perhaps not much experience working with relatively immature open source software projects. I don't think they understood what an important resource the community is for finding information.
Or if he abhors community, I've heard that DC has also for-pay courses.
My reason for posting this is what I said in the subject, a reality check. I love the enthusiasm that the Zope community has in general. But I think that the Zope community is largely made up of individuals who already really love Zope.
Yep. Most who can't grasp even the most simplest things about zope after a few weeks _dedicated_ effort and are too shy to ask do leave :)
I wanted to present the viewpoint of someone who has no bias for or against Python or Zope. I wanted to present an evaluation solely on the merits of whether it could get their job done. I wanted to point out what those people say Zope needs to have in order to win them over.
Maybe we need some meta-meta document about where to find what (btw, Zope is HUGE, they don't speak about zen of zope for nothing, it has mirrors within mirrors within mirrors ;)
If you imply that they are not experienced enough or intelligent enough or open-minded enough to use Zope then you are missing the point. Zope is a tool for web programmers, not Python programmers. It has to be useful to them if it is going to be successful.
You can do quite a lot of web-databse programming without writing a single line of Python, but you need to have two things : 1) a working Databse Adapter (I've never set up Oracle DA for Zope, but I remember from my Oracle days that setting up Oracle client could be quite an ordeal) 2) knowledge (or docs) of SQL. Most of Zope docs on DAs seem to imply that people using them know SQL or can guess the meaning of INSERT, UPDATE, DELETE and SELECT from examples. -------------- Hannu
1. What platform did they implement it on? 2. The documentation can be improved on, but I have to question the "fast research guys" ability if after several weeks he couldn't get anywhere. I am afraid that no matter how good the documentation is he would still battle by the sound of things. 3. What product is there yet? and what is "there" On Fri, 10 Dec 1999, you wrote:
I thought this forward would be of interest to the DC folks and the community at large.
-jfarr
Zope has some of the worst documentation I have ever encountered. I paged through it for a while and was unable to get to any actual information, just marketing-esque hype. I turned the investigation over to my typically very fast research guy, figuring maybe I just had the wrong set of docs or something; after learning Python and spending several solid weeks of trying to figure out how to get it to update objects in Oracle (vs. just view them), he gave up on it; we aren't going to use it.
It's a good idea, and I hear only good things about Python, but Zope is Just Not There Yet.
YMMV, Brenda
_______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope No cross posts or HTML encoding! (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev ) -- Craig P Avnit Director London Plaza Ltd Tel: +44 (0)7000 64-5768 Fax: +44 (0)7000 64-5769 http://www.londonplaza.co.uk
In article <0ad401bf42c0$43bcbd60$eb0217ac@dev.prognet.com>, Jonothan Farr <jfarr@speakeasy.org> writes
I thought this forward would be of interest to the DC folks and the community at large.
-jfarr
Zope has some of the worst documentation I have ever encountered. I
.....
It's a good idea, and I hear only good things about Python, but Zope is Just Not There Yet.
YMMV, Brenda
.... I'm a real enthusiast of Zope and have a live site waiting to be validated by the funding body that uses python via external methods etc. I too find the Zope documentation absolutely opaque. Why can't we have all the little _p _v _aq tricks documented? I know there are documentation lumps in the sources, but it's a bad idea to dish up stuff which modifies the relatively clean python semantics without explicit documentation. How does one display structured text? -- Robin Becker
Robin Becker wrote:
In article <0ad401bf42c0$43bcbd60$eb0217ac@dev.prognet.com>, Jonothan Farr <jfarr@speakeasy.org> writes
I thought this forward would be of interest to the DC folks and the community at large.
-jfarr
Zope has some of the worst documentation I have ever encountered. I
.....
I'm a real enthusiast of Zope and have a live site waiting to be validated by the funding body that uses python via external methods etc.
I too find the Zope documentation absolutely opaque. Why can't we have all the little _p _v _aq tricks documented? I know there are documentation lumps in the sources, but it's a bad idea to dish up stuff which modifies the relatively clean python semantics without explicit documentation.
Did'nt you read why DC made Zope open-source - they want to make money on consulting ;) <grin> But seriously, what I would (have) need(ed) in documentation is not so much descriptions of Zope but more _examples_ of doing common things. Zope _is_ quite different from what one expects (even the templates are backwards), and thus has the typical ease-of-us vs. ease-of-learning controversy of advanced tools. btw, where did the help pages that were present in 1.10.3 disappear in 2.0 ?
How does one display structured text?
<dtml-var the_text fmt=structured-text> ----------------- Hannu
In article <3850CEBB.2D1B93DA@tm.ee>, Hannu Krosing <hannu@tm.ee> writes
Robin Becker wrote: ...
<dtml-var the_text fmt=structured-text>
----------------- Hannu
thanks for that. I guess now I have to create my own pages linking them all together. -- Robin Becker
Hello All! Am 10-Dec-99 schrieb Jonothan Farr:
Zope has some of the worst documentation I have ever encountered.
This is sad, but almost true. Although the docs are nicely enriched with fancy screen-shots, the information provided does not go into too much detail. I am new to Zope and right now I am studying the docs really carefully. Just yesterday I encountered a Problem related to <dtml-tree>-tags. I found a section within "Zope Document Template Markup Language" entitled "Displaying Information Hierarchically: the dtml-tree". I typed the Quick example and it worked, ok so far. But I did not want to display all content of the current directory (excluding folders) so I started working on that, but that took me several hours. Sorry, but most examples do just scratch the surface of real problems. By the way, has anybody checked for the Index? I found several entries within the Index pointing to wrong pages. (e.g. "objectValues" points to page 57 (which is of course the 57th page as a pdf-document, but objectValues is mentioned on page number 49 in print (quite irritating))).
I
paged through it for a while and was unable to get to any actual information, just marketing-esque hype.
That is of course not really true. Regards, Ingo. ------------------------------------------
At 7:40 PM -0800 12/9/99, Jonothan Farr wrote:
[...]
Zope has some of the worst documentation I have ever encountered. I paged through it for a while and was unable to get to any actual information, just marketing-esque hype. I turned the investigation over to my typically very fast research guy, figuring maybe I just had the wrong set of docs or something; after learning Python and spending several solid weeks of trying to figure out how to get it to update objects in Oracle (vs. just view them), he gave up on it; we aren't going to use it.
It's a good idea, and I hear only good things about Python, but Zope is Just Not There Yet.
YMMV, Brenda
Evidently this person has very limited computer experience. Zope doesn't have the best docs, but somebody with some experience and an open mind can easily pickup Zope from the existing docs, which as far as I can tell, continue to get better all the time. When I started all of this Python was new to me as well and it far less than weeks to figure out how to write external methods (see the example in the documentation) and to get Zope inserting and updating information in a Pygresql (also new to me) database. Josh ___________________________________________ Joshua Brauer joshua@brauer.org http://www.brauer.org ___________________________________________
I think the Doc are pretty good seeing how fast Zope has been changing. Sound like a peson who wants a Point and Click Solution and he's just mad because he can't click up a good site with frontpage98. EOT Joshua Brauer wrote:
At 7:40 PM -0800 12/9/99, Jonothan Farr wrote:
[...]
Zope has some of the worst documentation I have ever encountered. I paged through it for a while and was unable to get to any actual information, just marketing-esque hype. I turned the investigation over to my typically very fast research guy, figuring maybe I just had the wrong set of docs or something; after learning Python and spending several solid weeks of trying to figure out how to get it to update objects in Oracle (vs. just view them), he gave up on it; we aren't going to use it.
It's a good idea, and I hear only good things about Python, but Zope is Just Not There Yet.
YMMV, Brenda
Evidently this person has very limited computer experience. Zope doesn't have the best docs, but somebody with some experience and an open mind can easily pickup Zope from the existing docs, which as far as I can tell, continue to get better all the time. When I started all of this Python was new to me as well and it far less than weeks to figure out how to write external methods (see the example in the documentation) and to get Zope inserting and updating information in a Pygresql (also new to me) database.
Josh
___________________________________________ Joshua Brauer joshua@brauer.org http://www.brauer.org ___________________________________________
_______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope No cross posts or HTML encoding! (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )
-- "One World, one Web, one Program" - Microsoft promotional ad (circa 1995) "Ein Volk, ein Reich, ein Fuhrer" - Adolf Hitler Under US Code Title 47, Sec.227(b)(1)(C), Sec.227(a)(2)(B) This email address may not be added to any commercial mail list with out my permission. Violation of my privacy with advertising or SPAM will result in a suit for a MINIMUM of $500 damage per incident.
participants (14)
-
Alexander Limi -
Chris McDonough -
Christopher Petrilli -
Craig P Avnit -
Hannu Krosing -
Ingo Assenmacher -
Jason Cunliffe -
Jonothan Farr -
Jonothan Farr -
Joshua Brauer -
ozric -
Patrick Phalen -
Rik Hoekstra -
Robin Becker