The agony of the ZOPE Documentation
I'm sorry, but I have to say, the ZOPE documentation, despite efforts to improve it, is absolutely, positively horrible. Not because the content isn't there, but because the tools to access it simply suck. I can type in searches on both zope.org and zdp.zope.org and though I KNOW the information is there, I can't get the results I want! Constantly, when I am recommending ZOPE to people, the ONE thing I and they complain about is the horrible documentation! Is there some way that I can get a copy of all of the FAQ's, HOW-TOs, Ref manuals, etc in some kind of raw ASCII text format or HTML or something, so that I can build some kind of useful search engine for this stuff? The search engines on www.zope.org and zdp.zope.org just plain suck. Additionally, the zdp web site is a real nice idea that is SO poorly executed IMO as to make it totally unusable. You can't even browse the documentation without clicking through a thousand different links. (I can give you specific examples of how to improve the site if you want.) Please, anyone? Save Zope's documentation! -- Some husbands are living proof that a woman can take a joke.
jiva@devware.com wrote:
I'm sorry, but I have to say, the ZOPE documentation, despite efforts to improve it, is absolutely, positively horrible. Not because the content isn't there, but because the tools to access it simply suck.
Gotta agree with this :(
Additionally, the zdp web site is a real nice idea that is SO poorly executed IMO as to make it totally unusable.
ZDP is currently undergoing a lot of development and unfortunately I have to agree that it isn't there yet... Unfortunately, no-one is getting paid to do it, and everyone who is working on it would probably get fired if they spent enough time on it to REALLY get the job done... I reckon there's about 25 man weeks of work to do based on 5 people spending: -1 week to build the tools -1 week to plan the structure of the documentation -3 weeks to get ALL the Zope documentation linked in one place (which is what zdp is supposed to be...) So, has anyone got the cash? ;-) Once this is done, it will be less work to keep that documentation up to date. Hopefully, eventually, all documentation would end up on zdp.zope.org and not just be linked from it...
You can't even browse the documentation without clicking through a thousand different links.
I agree here too :( (I can give you specific examples of how to improve the site
if you want.)
Send them to zdp@zope.org, in fact, better still, JOIN zdp@zope.org and go and make the changes yourself :-) Good luck, I think you're (or should that be 'we're all') going to need it... Chris
Hi ! Chris Withers wrote:
jiva@devware.com wrote:
I'm sorry, but I have to say, the ZOPE documentation, despite efforts to improve it, is absolutely, positively horrible. Not because the content isn't there, but because the tools to access it simply suck.
Gotta agree with this :(
Have you seen the logo of the ZDP site ? ;-)
Additionally, the zdp web site is a real nice idea that is SO poorly executed IMO as to make it totally unusable.
Thanks for telling me what you think about the ZDP site. The portal is only 24 days old, and we still need to fill in all the subjects and topics. Do think that the basic idea of offering different portals for different communities (Beginners, Developers and so on) is a bad idea ? What do you think about the organisation in Subjects/Topics ?
ZDP is currently undergoing a lot of development and unfortunately I have to agree that it isn't there yet...
We desparately need people helping !
Unfortunately, no-one is getting paid to do it, and everyone who is working on it would probably get fired if they spent enough time on it to REALLY get the job done...
The problem is that not all stakeholders are working on this together. The ZDP project has got another server than the main Zope site, and there are only a few spare time developers working on this site. If we could work together with Digital Creations and perhaps on the same server as Zope.org, things would be much easier !
I reckon there's about 25 man weeks of work to do based on 5 people spending: -1 week to build the tools -1 week to plan the structure of the documentation -3 weeks to get ALL the Zope documentation linked in one place (which is what zdp is supposed to be...)
So, has anyone got the cash? ;-)
This is a job that only DC can do right now. The ZDP has "only" got the aim to point to existing stuff. Restructuring the existing docs is not our job.
Once this is done, it will be less work to keep that documentation up to date. Hopefully, eventually, all documentation would end up on zdp.zope.org and not just be linked from it...
At least we can dream, can't we ? ;-)
You can't even browse the documentation without clicking through a thousand different links.
I agree here too :(
What documentation do you mean ?
(I can give you specific examples of how to improve the site
if you want.)
I really want to hear all your ideas !
Send them to zdp@zope.org, in fact, better still, JOIN zdp@zope.org and go and make the changes yourself :-)
It would be nice to get some help from the whole Zope community. Anyone who would like to give some ideas is more than welcome ! Greetings, Maik Röder -- Open Source is "about being able to work together with people you've never met, on projects that are in a constant state of flux, on a time schedule that would cause a hummingbird's head to spin." Paul Ferris, http://www.linuxplanet.com/linuxplanet/opinions/1593/1/
I posted this on ZDP but I thought I should put it here too. Chris Withers wrote:
Maik Roeder wrote:
The ZDP project has got another server than the main Zope site, and there are only a few spare time developers working on this site. If we could work together with Digital Creations and perhaps on the same server as Zope.org, things would be much easier !
I'm inclined to agree, why have a ZD portal when you could just have a Zope portal...
The ZDP has "only" got the aim to point to existing stuff. Restructuring the existing docs is not our job.
Maybe it should be? How about rebuilding zope.org as a generic 'Zope Portal' with the building and documenting work being done more by the community? (ie: integrating ZDP and Zope.org)
You got it. I think that the ZD portal and Zope.org should be seamlessly integrated. More to the point, I have the authority to make it happen on DC's end. I am *very* interested in integrating the community's effort more completely into Zope.org. Furthermore, this *is* a major part of what I need to do with Zope.org. It is, indeed, part of my Job Description: 4. Use direct assistance, tight documentation integration, collaborative tools and appropriate koans to provide a path to Zope Zen: a gentle learning curve that takes participants from novice DTML work to hacking zope internals So I *do* have time to help with this, and I don't imagine my employer will give me flack :) I will admit that I am not exactly up to speed on who's doing what with ZDP, nor am I trying to impose a vision. So what do you folks think? -- ethan mindlace fremen Zopista Community Liason
On Wed, May 24, 2000 at 09:50:08PM -0600, mindlace wrote:
I will admit that I am not exactly up to speed on who's doing what with ZDP, nor am I trying to impose a vision.
So what do you folks think?
I think the HOWTOs/tips are a bit redundant and some should be collapsed, expecially the shorter ones. It could not take much time.
Marco Mariani wrote:
On Wed, May 24, 2000 at 09:50:08PM -0600, mindlace wrote:
I will admit that I am not exactly up to speed on who's doing what with ZDP, nor am I trying to impose a vision.
So what do you folks think?
I think the HOWTOs/tips are a bit redundant and some should be collapsed, expecially the shorter ones. It could not take much time.
My personal opinion is that lack of documentation is the biggest barrier to someone new to Zope. You really do have to be somewhat agressive to find what you're trying to find (usenet+howto's+mailinglist searchs+altavista, etc). A comprehensive and complete (with examples) manual of DTML would be heavenly. Patrick
I must apologize in advance, I have not read the entire thread, but here's my answer to your question:
So what do you folks think?
My advice: be a benevolent despot. I started to get involved with ZDP many months ago, and proposed a structure for documentation, created a folder hierarchy to support the proposed framework (some of which was still evident on the ZDP site for a long time), and generally got zero feedback or support. My perception of the problem was that no one was in charge, no one could say yeah or nay, and no one said "This looks like a good direction for now, let's pursue it". Not that I necessarily thought that my work was the ultimate answer, but no one else was either proposing an alternative or suggesting needed modification. Instead, other folks just did their own thing. Now it looks like individuals get energized, produce a body of work (e.g. ZBook, ZQR) and then get burned out. My suggestions are, in decreasing preference: - consult with experts in learning/documentation design to come up with a framework for documentation; and/or, - find a site, product, book, or documentation set for a comparable product, and copy ideas from it; and/or, - work with ZDP activists and the mailing lists to come up with a framework, identify materials and formats to fit the framework, identify gaps, and then start assembling the structure. This is my least preferred path just because I'm skeptical that a group effort will move fast enough. I recognize that this is counter to Open Source practice, but I really believe inadequate documentation is the main barrier between Zope and world domination! And good luck! Zope remains a great tool with an excellent user/support base, let's make it better. Craig
I reckon there's about 25 man weeks of work to do based on 5 people spending: -1 week to build the tools -1 week to plan the structure of the documentation -3 weeks to get ALL the Zope documentation linked in one place (which is what zdp is supposed to be...)
So, has anyone got the cash? ;-)
Well I have asked a few times before, before but never a reply.. so I will ask again: How much would it cost? (U$?) How many people on these lists are willing to contribute some money towards the zdp work? I am. I buy books and magazines all the time - do you? How much do you spend over, say, 3 months on printed matter? How much would it worth over the next 3 months X how many people to move this work along significantly? Perhaps you have no time but some money.. I am not saying that money is the magic answer - clearly ZDP needs intelligent dedicated contribution and feedback. But there does appear to be some basic work to be done and not enough humna resources to go round. And money might really help out here... It seems like rather a catch-22 [or is that a zope-22] : until the docs are in better shape, it is so much harder for more people to contribute usefully because it is so easy to get lost again.. ZDPLINE.COM ?? Perhaps someone with better dtml skills than I can make a little mini priceline.com app for zdp.. Everyone/Anyone wishing to contribute something towards documentation logs on and enters the amount: instant tally shows total potential sponsorship with column for person-hours/days at rate. Instead of a well intentioned message thread which will be rapidly drownded in a sea of DTML minutuae, we can have visible target + 'potential' zdp attractor When we hit a 'u$eful 'threshold - $ponsors kick in with their actual contrib. and zdp advances. Perhaps you have a better crazier idea..I hope so:-) Meanwhile, some fascinating and surreal reading: Interview with Jay Walker http://www.strategy-business.com/thoughtleaders/00209/page1.html my $0.25 - Jason
Jason Cunliffe wrote:
I reckon there's about 25 man weeks of work to do based on 5 people spending: -1 week to build the tools -1 week to plan the structure of the documentation -3 weeks to get ALL the Zope documentation linked in one place (which is what zdp is supposed to be...)
So, has anyone got the cash? ;-)
Well I have asked a few times before, before but never a reply.. so I will ask again:
How much would it cost? (U$?)
Based on the above figures, and assuming £500/day/person, it comes out as: £62,500 (roughly $100,000)
Perhaps you have no time but some money..
Personally, I have neither ;-)
resources to go round. And money might really help out here...
I agree, I would love to do it, and I'm sure my employer wouldn't mind if someone else was footing the bill ;-)
It seems like rather a catch-22 [or is that a zope-22] : until the docs are in better shape, it is so much harder for more people to contribute usefully because it is so easy to get lost again..
I agree :-)
ZDPLINE.COM ??
$ whois zdpline.com Whois Server Version 1.1 Domain names in the .com, .net, and .org domains can now be registered with many different competing registrars. Go to http://www.internic.net for detailed information. No match for "ZDPLINE.COM". Well, the name is there... ;-) cheers, Chris
Perhaps someone with better dtml skills than I can make a little mini priceline.com app for zdp..
Everyone/Anyone wishing to contribute something towards documentation logs on and enters the amount: instant tally shows total potential sponsorship with column for person-hours/days at rate. Instead of a well intentioned message thread which will be rapidly drownded in a sea of DTML minutuae, we can have visible target + 'potential' zdp attractor
When we hit a 'u$eful 'threshold - $ponsors kick in with their actual contrib. and zdp advances. Perhaps you have a better crazier idea..I hope so:-)
Meanwhile, some fascinating and surreal reading: Interview with Jay Walker http://www.strategy-business.com/thoughtleaders/00209/page1.html
my $0.25 - Jason
Well I have asked a few times before, before but never a reply.. so I will ask again:
How much would it cost? (U$?)
Based on the above figures, and assuming £500/day/person, it comes out as:
£62,500 (roughly $100,000)
ouch!Interesting.. .And if you write a book, how much will a publisher pay you [for example ORA 'Zope in a Nutshell']. ..and how many copies do you think ZIAN [Zope in a Nutshell] will sell ? Is this why/how FrontierLand/Manila asks $899/year ? http://store.userland.com/default.html or Roxen SEK 95,000.00 = 10,308.75 USD http://www.roxen.com/store/ etc
Based on the above figures, and assuming �500/day/person, it comes out as:
�62,500 (roughly $100,000)
ouch!Interesting.. .And if you write a book, how much will a publisher pay you [for example ORA 'Zope in a Nutshell']. ..and how many copies do you think ZIAN [Zope in a Nutshell] will sell ?
Well, I for one would be at the front of the queue to buy a copy. In fact, if nothing comes to light by the end of the year I wonder if NIP would finance a sabbatical for me to write one? ;-) Seriously though, I think there's a big demand for something like this, more so considering how fast Zope seems to have come in such a short time. In the worst case, maybe O'Reilly would consider an extra chapter to, say, a third edition of the excellent "Webmaster in a Nutshell"? John -- John Chandler / Software Developer / New Information Paradigms Ltd [ Linux in the office, AmigaOS in the home, PalmOS in the pocket ] ------------------------------------------------------------------------ The opinions above aren't those of my company... ...but then, they aren't really mine either.
John Chandler wrote:
ouch!Interesting.. .And if you write a book, how much will a publisher pay you [for example ORA 'Zope in a Nutshell']. ..and how many copies do you think ZIAN [Zope in a Nutshell] will sell ?
Well, I for one would be at the front of the queue to buy a copy. In fact, if nothing comes to light by the end of the year I wonder if NIP would finance a sabbatical for me to write one? ;-)
I think Mike Pelletier has a contract to do this already... I guess he just needs to find the time :S (of course, any book would be out of date by the time it's published, o I'm not sure of the usefulness...) Chris
Well, let me see..... I would consider giving the summer to working on Zope Documentation in Exchange for Zope School. That's right, I'm as much a newbie to Zope as that egg they are breaking in the Perl2Zope thread. But I live 20 minutes from Zope Headquarters.....Fredericksburg, eh? I like working long hours and am probably going to be available through mid august/september. The downside is that I am "really new" to zope and python. The upside is that I'm into it.... It would be a good backgrounder for that book I've always wanted to write about something... ----- Original Message ----- From: "Chris Withers" <chrisw@nipltd.com> To: "Jason Cunliffe" <jasonic@nomadicsltd.com> Cc: <zope@zope.org>; <zdp@zope.org> Sent: Wednesday, May 24, 2000 4:47 PM Subject: [Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation Jason Cunliffe wrote:
I reckon there's about 25 man weeks of work to do based on 5 people spending: -1 week to build the tools -1 week to plan the structure of the documentation -3 weeks to get ALL the Zope documentation linked in one place (which is what zdp is supposed to be...)
So, has anyone got the cash? ;-)
Well I have asked a few times before, before but never a reply.. so I will ask again:
How much would it cost? (U$?)
Based on the above figures, and assuming £500/day/person, it comes out as: £62,500 (roughly $100,000)
Perhaps you have no time but some money..
Personally, I have neither ;-)
resources to go round. And money might really help out here...
I agree, I would love to do it, and I'm sure my employer wouldn't mind if someone else was footing the bill ;-)
It seems like rather a catch-22 [or is that a zope-22] : until the docs are in better shape, it is so much harder for more people to contribute usefully because it is so easy to get lost again..
I agree :-)
ZDPLINE.COM ??
$ whois zdpline.com Whois Server Version 1.1 Domain names in the .com, .net, and .org domains can now be registered with many different competing registrars. Go to http://www.internic.net for detailed information. No match for "ZDPLINE.COM". Well, the name is there... ;-) cheers, Chris
Perhaps someone with better dtml skills than I can make a little mini priceline.com app for zdp..
Everyone/Anyone wishing to contribute something towards documentation logs on and enters the amount: instant tally shows total potential sponsorship with column for person-hours/days at rate. Instead of a well intentioned message thread which will be rapidly drownded in a sea of DTML minutuae, we can have visible target + 'potential' zdp attractor
When we hit a 'u$eful 'threshold - $ponsors kick in with their actual contrib. and zdp advances. Perhaps you have a better crazier idea..I hope so:-)
Meanwhile, some fascinating and surreal reading: Interview with Jay Walker http://www.strategy-business.com/thoughtleaders/00209/page1.html
my $0.25 - Jason
_______________________________________________ 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 )
jiva@devware.com wrote:
I'm sorry, but I have to say, the ZOPE documentation, despite efforts to improve it, is absolutely, positively horrible. Not because the content isn't there, but because the tools to access it simply suck. I can type in searches on both zope.org and zdp.zope.org and though I KNOW the information is there, I can't get the results I want! Constantly, when I am recommending ZOPE to people, the ONE thing I and they complain about is the horrible documentation!
It would be very helpful if you would take a look at the new help system in the latest alpha release. Or even better, check out Zope via CVS and try that out. I may be biased, but I think it's real progress. Just push the "help" button on most management screens. Shane
Thanks shane, I'll check it out! :) On Wed, May 24, 2000 at 05:12:36PM -0400, Shane Hathaway wrote:
jiva@devware.com wrote:
I'm sorry, but I have to say, the ZOPE documentation, despite efforts to improve it, is absolutely, positively horrible. Not because the content isn't there, but because the tools to access it simply suck. I can type in searches on both zope.org and zdp.zope.org and though I KNOW the information is there, I can't get the results I want! Constantly, when I am recommending ZOPE to people, the ONE thing I and they complain about is the horrible documentation!
It would be very helpful if you would take a look at the new help system in the latest alpha release. Or even better, check out Zope via CVS and try that out. I may be biased, but I think it's real progress.
Just push the "help" button on most management screens.
Shane
-- I'm pretending that we're all watching PHIL SILVERS instead of RICARDO MONTALBAN!
Shane Hathaway wrote:
jiva@devware.com wrote:
I'm sorry, but I have to say, the ZOPE documentation, despite efforts to improve it, is absolutely, positively horrible. Not because the content isn't there, but because the tools to access it simply suck. I can type in searches on both zope.org and zdp.zope.org and though I KNOW the information is there, I can't get the results I want! Constantly, when I am recommending ZOPE to people, the ONE thing I and they complain about is the horrible documentation!
It would be very helpful if you would take a look at the new help system in the latest alpha release. Or even better, check out Zope via CVS and try that out. I may be biased, but I think it's real progress.
Just push the "help" button on most management screens.
Yes the help system is great. Also check out the various Wikis on Zope.org where the new flava of documentation is emerging as we speak. http://www.zope.org/Members/WikiCentral -- -Michel Pelletier http://www.zope.org/Members/michel/MyWiki Visit WikiCentral for the latest Zen: http://www.zope.org/Members/WikiCentral
I too was struggling to stay sane while coding in DTML, until I came across this little beauty from AlexR. http://www.zope.org/Members/AlexR/ZopeDocs He has combined Howto's and Tip's into PDF's, with nice contents pages and you can easily search PDF's. Hope this helps ! Peter Marriott -----Original Message----- From: zope-admin@zope.org [mailto:zope-admin@zope.org]On Behalf Of jiva@devware.com Sent: Thursday, 25 May 2000 3:00 AM To: zope@zope.org Subject: [Zope] The agony of the ZOPE Documentation I'm sorry, but I have to say, the ZOPE documentation, despite efforts to improve it, is absolutely, positively horrible. Not because the content isn't there, but because the tools to access it simply suck. I can type in searches on both zope.org and zdp.zope.org and though I KNOW the information is there, I can't get the results I want! Constantly, when I am recommending ZOPE to people, the ONE thing I and they complain about is the horrible documentation! Is there some way that I can get a copy of all of the FAQ's, HOW-TOs, Ref manuals, etc in some kind of raw ASCII text format or HTML or something, so that I can build some kind of useful search engine for this stuff? The search engines on www.zope.org and zdp.zope.org just plain suck. Additionally, the zdp web site is a real nice idea that is SO poorly executed IMO as to make it totally unusable. You can't even browse the documentation without clicking through a thousand different links. (I can give you specific examples of how to improve the site if you want.) Please, anyone? Save Zope's documentation! -- Some husbands are living proof that a woman can take a joke. _______________________________________________ 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 )
jiva@devware.com wrote:
I'm sorry, but I have to say, the ZOPE documentation, despite efforts to improve it, is absolutely, positively horrible. Not because the content isn't there, but because the tools to access it simply suck. I can type in searches on both zope.org and zdp.zope.org and though I KNOW the information is there, I can't get the results I want!
Ok. This only vaguely begins to address your issues, but I went ahead and added searching Zope.org with Google to the "search" page- the one you get for clicking on the "search" link at the top of the page. For example, I searched for dtml-+in (had to add the +, because "in" is a stop-word) and got loads of relevant results. Hope this helps a tiny bit. Digital Creations did just recently hire me, in part, to fix the tools to access the documentation, so you can expect it to get better soon. Thanks, ethan mindlace fremen Zopista Community Liason
participants (13)
-
Chris Withers -
Craig Allen -
J. Michael Mc Kay -
Jason Cunliffe -
jiva＠devware.com -
John Chandler -
Maik Roeder -
Marco Mariani -
Michel Pelletier -
mindlace -
Patrick J.M. Keane -
Peter Marriott -
Shane Hathaway