[Zope3-dev] 10x growth for Zope? Never without docs

[Martijn Faassen]

Jon Whitener wrote:
> Upon noticing the stated desire to grow Zope usage "10x", I'm compelled to chime in as a Zope newbie.  If Zope wants to grow ten times, here's your solution:
> 
>   DOCUMENTATION!

Okay, you write it then. :) This has been a recurring topic since '99 or so, so
pardon my reaction. There is now quite a bit of documentation about Zope, in fact,
compared to '99 where there was a bit about DTML and that was basically it.
Quite a number of books as well. It needs a lot more work, so start an
effort. There's a Zope Documentation Project that's currently
moribund as the people who were active in it moved on (I was early on
but have other concerns now). 

> Now you need to concentrate on providing details about Zope for the many more content-oriented Web site makers who are not and have not full-time programmers / developers.  These potential users just want to make Web sites.  Zope could enable that.  Zope cannot enable that without good documentation.

In the current Zope 3 world this is a bit premature. Right now Zope 3
is not useable by anyone, though Python programmers will get
furthest. This will change in the future, but even documentation
efforts will focus on developer documentation right now, not 
the target audience you mention. We're very aware of this
target audience, but it's a bit early to document things. :)

> Users want to do nothing less than fritter away precious time on documentation treasure-hunts.  The Zope Book?  What software would anyone ever use where we go to the official doc thinking "Oh, no, I really hope Chris McDonough had enough time to work on the ZPT chapter some more!"  That's the whole problem in a nutshell.

This is probably why there's a whole shelf about Oracle or Dot.Net or Java
and so on at the bookstore, right? It's because the official
documentation contains all the answers. :)

Anyway, right now for Zope 3 there is the following documentation:

  * unstructured stuff on the wiki. Design notes.
  
  * this mailing list.

  * zope3-dev on irc

  * Lots and lots of interfaces in the source code. This is
    API documentation. This documentation is rather extensive,
    though brief.

  * lots of unit tests that exercise the code (over 2000)

  * a tutorial presentation for developers

As you see there is not much and all very techie. Though I think actually this
may exceed the documentation there was for Zope 2 in '99. :)

Somewhere between the first alpha (this year Jim hopes) and some beta we
need to seriously think about tutorials and so on to guide beginners.
Right now concentrating on such basics as the user interface
are more important though, I think. :)

> The people who could become a large part of Zope's user base want to make Web sites, not play MYST.  I deeply hope the Zope Powers-That-Be awaken to the seriousness of the lack of good documentation.

They're too busy writing software. :) Someone else will have to write
the documentation. What about you?

Perhaps your mail was directed to the wrong mailing list; it's
about zope 3 development. Zope 3 is currently somewhere between
vaporware and alpha state. Perhaps you would try to herd some
people from the other zope lists onto the ZDP list or some other
forum and do some work on Zope 2 documentation.

If you're really interested in providing Zope 3 documentation
instead then please start participating here and create
a plan for Zope 3 documentation, and my thanks go to
you. In some cases writing documentation before writing code will
actually help, so you could start with that right away.

Regards,

Martijn