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 )
[Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation
-Original Message-
From: Jerry Spicklemire <[EMAIL PROTECTED]>
To: [EMAIL PROTECTED] <[EMAIL PROTECTED]>
Date: donderdag 25 mei 2000 1:11
Subject: [ZDP] Re: [Zope] The agony of the ZOPE Documentation
>(forwarded from [EMAIL PROTECTED])
>
>Jason Cunliffe wrote:
>
>Perhaps you have a better crazier idea..I hope so:-)
>
>Maybe. I too have had problems with the ZDP stuff, but not specifically
>those mentioned by others in this thread. When I try to use the ZDP I am
>impressed by the effort and sheer volume of material, but unfortunately it
>seems to be mostly supported by non-native English speakers. The result is
>that I am often uncertain that I clearly understand what the author
>intended. That leaves me in a state that is nearly worse that where I
>began, potentially more knowledgable, but certainly more confused. Now, for
>that crazy solution.
>
>If the ZDP were in some Wiki-ish form that could be edited by readers
>("Edit This Page", a la Frontier?), a new version of a page could be
>created to fix the most obvious misexpressions. The author might then be
>able to review the updates, and either approve the fixes, or clarify cases
>where a misfix has resulted from a misinterpretation, which itself is a
>verifiable indication that the original text was somewhat obscure. After a
>few passes through this process, the ZDP might be dressed up and ready to
>go to press!
>
>In a case like the proposal above, anyone willing to do some copyediting
>would be free to edit a paragraph at a sitting, if that's the all the time
>available, or a page, or a chapter. Whatever works. I know I have been
>reluctant to commit to any extensive participation simply because my time
>is very limited. Still, as tight as the schedule is, it isn't quite in the
>negative microseconds yet, so a graph per shift is better than nothing!
>
>With this in mind see the very recent post:
>
> http://lists.zope.org/pipermail/zope-dev/2000-May/005021.html
>
>This is a way to manage Zope Objects, stuff that usually lives in ZODB,
>using CVS. This can provide versioning, checkout, checkin, etc. It could be
>used as a way to let ZDP Authors know what's changed, at a very granualr
>level, to keep from having to wade through the page looking for somthing
>that isn't precisely as it was last time they saw it. ZDP is itself a Zope
>site, so this could be just the ticket.
>
Perhaps, but i think this is not necessary (though I liked the product
idea). Should you become a member of the ZDP site, than Maik already created
many such tools, including commenting, reviewing, discussing etcetera (and
search possibilities for documentation that needs it). We badly need people
for these tasks, though, and nobody has taken these tasks up yet. Mindlace
just yet announced serious involvement by DC, but we never had input from
them before (sorry to say so)
Please take into account that at the moment the whole ZDP, including
programming, writing documentation etc, takes the effort of far less than
ten people, who work at it in their spare time. Or to put it differently:
ZDP NEEDS CONTRIBUTORS, REVIEWERS, EDITORS, WRITERS
Help us out and the whole Zope community will benefit.
Rik
___
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
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 ___ 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] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation
> > 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. > Good. We (=zdp list) pleaded various times for an integration of ZDP and Zope documentation. >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, Neither are we, and moreover everything there is in a flux. We called it comfortable anarchy when ZDP just started, and so it's stayed ever since. >nor am I trying to impose a vision. > >So what do you folks think? 1) I have pleaded before for ownership of several documentation efforts. We now have something called maintainers on the ZDP site (Maik overall maintenance, ZBook Tom Deprez I suppose, Kamon Ayeva - hm, something else, and me ZSnippets). Perhaps ownership is taking it to far, but a bit of coordination left and right and (taking initiatives for) setting priorities would do much good. So far, no one is inclined to take responsability for more than a part, though. 2) The ZDP Tools of Maik Roeder and the Subject/Topic hierarchy stuff by David Kankiewitz (if I spell his name right) are great stuff with a lot of potential, even if they may not appear consistently on the ZDP site right now (to say the least). There is some documentation available about them somewhere, but Maik may be able to answer questions better. my 2 cents Rik ___ 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] 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
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 ___ 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
Maik Roeder <[EMAIL PROTECTED]> writes: > 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 ? Well, as a brand-spanking new user (or user wannabe, if I can get the tutorial to run), I think that offering portals at all is a bad thing. I want information, not hoops to jump through to get information. Part of this is that I don't really like portals much in general, but a large part of it is that when I have problems, I go looking for information to solve those problems, and I don't want to have to guess where something would be filed (kind of hard when you don't know much). The current portal segments information based on what kind of "user" you are, but in reality, my problems involve information which might be found in many places, and I have to dig through all of them to find out where. It might be better if all information were contained in all portals, but organized differently. Right now, as a "new user & developer" I have a portal that's empty... not even a link to the faq! That's a big help! > 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. Well, why is it called the Zope Documentation Project, if it's not supposed to provide documentation? Oh, wait... it's not, I guess. I hadn't looked at the title on http://zdp.zope.org before, but the link at http://www.zope.org/Documentation says it's project (and a source of documentation). > What documentation do you mean ? Well, there's the Zope Book project which requires lots of clicking (and it took me a little while to figure out that there was actually content on the sub-sections, because the interface changed on me). Personally, I haven't gotten any further, because I just started. -- Alan Shutko <[EMAIL PROTECTED]> - In a variety of flavors! 170 days, 17 hours, 37 minutes, 27 seconds till we run away. Your mind understands what you have been taught; your heart, what is true. ___ 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 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 ___ 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
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] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation
> 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 ___ 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 )
