Re: [Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation

2000-05-29 Thread Craig Allen

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

2000-05-25 Thread J. Michael Mc Kay

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

2000-05-25 Thread John Chandler

  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 )




[Zope] Re: [ZDP] Re: [Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation

2000-05-25 Thread Rik Hoekstra

snip

  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

2000-05-25 Thread Chris Withers

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] The agony of the ZOPE Documentation

2000-05-25 Thread Rik Hoekstra


-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] The agony of the ZOPE Documentation

2000-05-25 Thread Amos Latteier

 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 )




Re: [Zope] The agony of the ZOPE Documentation

2000-05-24 Thread Chris Withers

[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

2000-05-24 Thread Maik Roeder

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 )




[Zope] Re: [ZDP] Re: [Zope] The agony of the ZOPE Documentation

2000-05-24 Thread Jason Cunliffe

 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

2000-05-24 Thread Chris Withers

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 )




Re: [Zope] The agony of the ZOPE Documentation

2000-05-24 Thread jiva

Thanks shane, I'll check it out! :)

On Wed, May 24, 2000 at 05:12:36PM -0400, Shane Hathaway 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.
  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!

___
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

2000-05-24 Thread Alan Shutko

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] The agony of the ZOPE Documentation

2000-05-24 Thread Michel Pelletier



Shane Hathaway 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.
  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

___
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

2000-05-24 Thread Peter Marriott

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: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]]On Behalf Of
[EMAIL PROTECTED]
Sent: Thursday, 25 May 2000 3:00 AM
To: [EMAIL PROTECTED]
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  -  [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] The agony of the ZOPE Documentation

2000-05-24 Thread mindlace

[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 )