[Zope3-dev] Re: Z3 documentation

[Jim Fulton]

Garrett Smith wrote:
> List, 
> 
> I've got some time over the next few months to contribute to the Z3
> effort. Having looked over the technology, there's not much I can
> contribute to in the way of coding -- too new to Python and Z3.
> 
> However, I might be able to help in the area of documentation. I've
> managed development efforts involving some commercial ISVs and have a
> pretty good idea what's involved in delivering high quality docs,
> particularly for frameworks and tools.

Great!

> Having read through the mailing list archives, I've made a few
> observations:
> 
>  - Z3 appears to be congealing (typical for alpha stage) and that's
> usually a great time to get docs going.
> 
>  - The list is starting to see frequent requests for better docs from
> the new and curious. The temptation is strong to respond with "write 'em
> yourself, y' whiner" -- but it helps if they have a process/project to
> plug into.

Yup. Yup.

...

> 1. Is now a good time for a more focused effort on "docs" for Z3?

Yup.

You've gotten lots of other responses, which I won't respond to.

I'll note a couple of things.

- I think that are times to use Wikis and times not to use Wikis.
   Wikis have the advantage that they make it easy to contribute.
   Some day, I'd like to see a much better Wiki than we have now.
   As Simon pointed out, perhaps new zope.org will give us a chance to
   catch up with current zwiki.

   In the mean time, we've been putting a lot of documentation in CVS.

   Any non-wiki docs should be in reStructuredText format. In theory,
   reST will let us generate things like docbook and even word,

- We've started the pattern of putting developers documentation in
   readme files for particular packages.  See, for example,
   src/zope/schema/readme.txt, src/zope/security/readme.txt, and
   src/zope/app/services/README.txt.  (I mean to rename all readme.txt
   files to README.txt.)  This documentation should be tutorial in nature.


- We need help organizing the material that is appearing.

   I understand Stephans's frustration with top-down approaches with
   outlines that never get filled in.  However, I think we are following a more
   bottom up approach.

   Our documentation is being developed as individual articles
   in wiki pages and readme files. We need someone to put some effort into
   organizing this with some tables of contents and other orienting material.

Jim

-- 
Jim Fulton           mailto:jim@zope.com       Python Powered!
CTO                  (703) 361-1714            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org