[ZDP] Documentation Solution

[Pam Crosby]

Thanks Eron,

Incorporating the Zope Documentation Projects effort into the *official*
documentation is an effort I am currently working towards.  I, too, am a
Zope newbie and I am struggling to extract information from the official
documentation to help my projects.  Fortunately, I have the experts in the
same office with me and I'm able to get the answers quickly.  Putting the
answers to paper and publishing them at several levels take time.  Much
time.

We announce several months ago our plans for documentation.  Amos, Rob and I
are currently establishing the *DC* Documentation Road Map.  There are some
technical issues to work out, as we need testers for our new process.

Rest assured that documentation solutions are being tested and all
suggestions are welcomed.

Pam Crosby
Technical Writer
Digital Creations
http://www.digicool.com
http://www.zope.org
mailto://pam@digicool.com



----- Original Message -----
From: Eron Lloyd <woodsage@op.net>
To: <zope@zope.org>; <zope-dev@zope.org>; <zdp@zope.org>
Sent: Saturday, December 11, 1999 9:09 PM
Subject: [ZDP] Documentation Solution


> As a member of the ZDP, as well as several other Documentation Projects,
> I understand exactly where these complaints are coming from. I'm still
> in the learning stage of Zope, and I admit, am stumbling over the
> current *official* documentation; nonetheless, I think I'm gaining a
> foothold. I'm not going to say what Digital Creations should do about
> this dilemma, but present several options:
>
> 1. Create a good communication with the ZDP. As far as I know, not much
> if any of the ZDP's effort has made it into official documentation.
> Let's encourage eachother, not point fingers. Let writers know that they
> are needed; even better, compile a list of EXACTLY what needs to be
> written/updated.
>
> 2. Have volunteers mine the mail archives and compile notes. There is
> TONS of excellent questions/answers to real world situations on
> everything Zope. Let's start going through and indexing them.
>
> 3. Put together TUTORIALS. If you know how to do something, document it.
> I'm sure someone would appreciate it. Contact the ZDP, and we'll put up
> a good collection.
>
> 4. Proofread. Many of the Official Guides have typos and broken code
> examples. Let Pam know. A simple page# description would help ALOT.
>
> 5. NEWBIES: Instead of just requesting help on something, request
> someone to make a How-to. This is another way we can gather priceless
> material instead of letting it dissolve into the mail archives.
>
> 6. A Hypertext help-system integrated into the Zope installation.
>
> 7. What tools? Here are some tools we could decide to use for docs
> (+/-):
>
> - DocBook SGML/XML DTD: Powerful, standardized; yet complex - VERY
> complex.
> - StarOffice: good Word Processor, supports multi-user docs (redlining,
> etc.), free; Big, some say bloated.
> - Structured Text: native to Zope, easy to write in; not functional
> enough, can't convert to different formats easily
> - CONGLOMERATE: This could be our answer - an XML-based Document
> editing/management system, FREE (GPL'd); not yet completed...
> (www.conglomerate.org)
>
> I thing Conglomerate could be our solution. But for now, let's bump
> heads and work together, and put reality back into check.
>
> Eron Lloyd
>
>
>
> _______________________________________________
> ZDP maillist  -  ZDP@zope.org
> http://lists.zope.org/mailman/listinfo/zdp
>