Re: [Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation
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 ___ Zope maillist - [EMAIL PROTECTED] 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 )
Re: [Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation
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" [EMAIL PROTECTED] To: "Jason Cunliffe" [EMAIL PROTECTED] Cc: [EMAIL PROTECTED]; [EMAIL PROTECTED] 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 - [EMAIL PROTECTED] 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 ) ___ Zope maillist - [EMAIL PROTECTED] 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 )
Re: [Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation
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. ___ Zope maillist - [EMAIL PROTECTED] 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 )
RE: [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! I know that Zope's documentation is frustrating. However, I generally find searches on Zope.org to be helpful. I've forwarded your concerns to the Zope.org webmaster. I'd like to share some what Michel Pelletier and I have been doing to improve Zope documentation. * We conducted a poll to help us determine what was most needed. We found out that Zope docs are of middling quality and folks most want new user help. * We wrote an online help system for Zope and wrote help content for all management screens. Right now we are updating this content for Zope 2.2. The help system will ship with Zope 2.2 and an alpha is available right now. * We've started a Zope API documentation process. Right now there is an extensive Zope API documentation wiki on Zope.org. The fruits of this labor will be API docs that will ship with Zope in the online help system. Right now several API docs are complete and are included in the current 2.2 alpha. * We've overhauled Zope training materials and will make them available publicly in the next week or so. * We're still working on Zope Guides and References replacements. I think that the training materials will be quite useful for this effort. I hope to have Guide and Reference replacements done by the end of the summer. Thanks for listening. If you have specific comments or questions about Zope documentation, please don't hesitate to let me know at [EMAIL PROTECTED] -Amos -- Amos Latteier mailto:[EMAIL PROTECTED] Digital Creations http://www.digicool.com ___ Zope maillist - [EMAIL PROTECTED] 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 )
[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 - [EMAIL PROTECTED] 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 )
Re: [Zope] The agony of the ZOPE Documentation
[EMAIL PROTECTED] 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 [EMAIL PROTECTED], in fact, better still, JOIN [EMAIL PROTECTED] 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 ___ Zope maillist - [EMAIL PROTECTED] 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 )
[Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation
Hi ! Chris Withers wrote: [EMAIL PROTECTED] 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 [EMAIL PROTECTED], in fact, better still, JOIN [EMAIL PROTECTED] 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/ ___ Zope maillist - [EMAIL PROTECTED] 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 )
Re: [Zope] The agony of the ZOPE Documentation
[EMAIL PROTECTED] 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 ___ Zope maillist - [EMAIL PROTECTED] 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 )
