[Zope-dev] Documentation

[Dody Gunawinata]

Let's us not forget that Zope is an open source product now. Having DC
doing most of the development of Zope sometimes
can make us forget that Open Source means a community collaboration.
That would include the documentation. It is clear
that the documentation currently lacks especially for beginners. But
that's not the fault of DC itself, because creating
documentation, especially for beginners can be a lot harder (and time
consuming because we have to assume that they know nothing), and DC
should spend time better on documenting and explaining the
latest/coolest features instead.

So it's up to us, the community, to create the 'book'. We do need a
'book' with decent chapters. Lots of how-to is nice if you are already
know what you are doing, but the information is fragmented, and it's no
use for beginners.

So, it's another project proposal..let's write a book on Zope.
Individual(s) can work on chapters after having agreed of the general
structures. We'll cover the basic from DTML, with working
projects/products example in the end, to Python programming, and up to
the
higher end. It's not an easy task as the transition from one chapter to
another needs to be carefully defined, as if it is not, they would be
difficult for new comer to use. An open source book. For the quality,
the 'book' should be good enough to be sold commercially in
bounded/printed form. A definitive guide to Zope. As this is electronic,
there is no limitation on how 'thick' the book can be. We can use tons
and tons of example in the 'book'.

Another requirement, they should use less the word 'namespaces' :0)..I
hate the word because I've seen loads of them in the current document
(and in Python tutorial as well)

So ?

Dody

jonathon wrote:
> 
> On Thu, 23 Sep 1999, Martijn Pieters wrote:
> 
> >At 03:50 23/09/99 , Dody Gunawinata wrote:
> >>I think "DOCUMENTATION" is more than anything else, the greatest barrier
> >>to people using Zope.
>         << paragraphs deleted >>
> >>Much of the documentation is designed with *advance* developers in mind.
> >>It's time for Zope for Dummies.
> 
> >What many people forget here is that Zope is a Web Application Platform. It
> >is, first and foremost, designed as a framework for applications.
> 
>         That doesn't negate the need for Documentation.
> 
> >marshalling of variable types and RDBMS integration, Zope makes one heck of
> >a Web Application Platform.
> 
>         True.  To use a Web Application Platform, one has to know the tools.
>         The easy way to find out what those tools are, and how to use them,
>         is by going through the documentation.
> 
> >Zope was designed for Web Application Developers, not designers. The
> >documentation follows this design. I actually feel that dummies should stay
> 
>         If one is an experienced Web Application Developer, the
>         documentation _might_ be, but probably isn't acceptable.
> 
>         If one is supposed to manage the content on a website, and
>         not an experienced Web Application developer, the documentation
>         is at best, inadequate.
> 
> >away from Zope. Frontpage is for dummies.
> 
>         What has Frontpage to do with Zope?  They are completely different
>         applications.
> 
>         One other point:
>                 Documentation can never contain too many examples.
> 
>         xan
> 
>         jonathon
> 
> _______________________________________________
> Zope-Dev maillist  -  Zope-Dev@zope.org
> http://www.zope.org/mailman/listinfo/zope-dev
> 
> (To receive general Zope announcements, see:
> http://www.zope.org/mailman/listinfo/zope-announce
> 
> For non-developer, user-level issues,
> zope@zope.org, http://www.zope.org/mailman/listinfo/zope )