[Zope] Use the source Luke -- what could be done to help documentation process? Request for comments!

[Chris McDonough]

> A while a ago there was discussion about the community stalling and the
> state of the documentation. As far as I can remember and see, there
> wasn't really any agreements or solutions what to do -- so I raise the
> question again -- and propably aim it to the people at Zope corp., what
> we -- noble users -- could do to help your work on documentation?


(FWIW, as of today, I am at least nominally in charge of documentation at
Zope Corporation.)

At the moment, I am concentrating on improving the state of the canonical
"booklike" docs (the Developer's Guide and the Zope Book).  Since it's a
part-time job (I'm also doing customer work), it's going to go pretty
slowly.  But it is going.  I'd love some feedback on what I'm doing and what
I plan on doing.

Here's what I've done so far:

  - Improved the BackTalk documentation system (a system for displaying
    and allowing comment on booklike content) to do simple things like
    accept multiline comments and not break when someone comments on
    a (preformatted) example paragraph.  See it at
    http://www.zope.org/Documentation/ZDG

Here's what I'm working on at the moment:

  - Enable automatic PDF generation from booklike sets of structured
    text documents (ala the Zope Book).  This will help form the basis
    for a new "canonical" documentation workflow that gets CVS
    out of the loop.

  - Make the "canonical" place for the Zope Book a BackTalk book in
    order to allow easy commentability.  Currently the Zope Book
    only allows comments via a SourceForge tracker.  The "canonical"
    version of the Zope Book is currently kept in CVS, which is not
    readily commentable by the average reader.

  - Develop a system for producing "release" documentation
    at each Zope release.  The release documentation will be immutable
    and downloadable in PDF and HTML.  For example, there will
    likely be PDFs and HTML tarballs of the DevGuide and Zope Book
    made for each Zope release.  The "canonical" version (in BackTalk)
    will be culled for comments at each release and edited.  Optimally,
    when a release is made, all the comments will be addressed and
    removed from the BackTalk version to start afresh.

Here's stuff that I want to do:

  - Get the ball rolling on the Zope Administrator's Guide again.  It's
    been stalled since last year.

I am a big fan of allowing comments to booklike documentation and using
those comments to improve later revisions of the documentation.  This is
actually pretty easy.  The *real* challenge is harnessing the energy and
work of the community that gets put into HowTos and ZopeLabs tips and
whatnot in a canonical place.  I'm not really sure how to do this. It's a
big job.  It requires actually sitting down and reviewing the mass of
content that exists, throwing away the old cruft and keeping and
categorizing the good stuff.  We don't have systems in place that let us do
this (or delegate this) effectively.  That means that a few motivated
individuals will need to bear the brunt of reviewing, editing, categorizing
all existing content on Zope.org.  Then a system will need to be built (or
repurposed -- ZDP) that makes the process easier the second time around. ;-)
Then the system needs to be used, which means it needs to be easy.

> We have a great community -- that is unfortunately in very many pieces
> around the world. Nice thing is the diversity, but in some cases the
> effiency suffers. Should one turn into ZDP, Zope zen, zope newbies,
> zopelabs or search through the mailinglists? Huh?

Right.  This is a hard problem.  Good thing we're in the content management
business. ;-)

Some options for improving the situation right now:

  - try to find all the best "nuggets" in the form of HowTos and whatnot
    and try to fold these into the Books (ZB and DevGuide) in the form of
    new chapters or paragraphs.

  - kickstart new.zope.org. (zzzz... ;-)  New.zope.org has a lot of the
    features that we've been wanting like workflow for docs and products,
    if it ever gets out.

> What I am suggesting is that together we create a certain set of methods
> of work, that we all will follow and help others to follow. These will
> include some etiquette on the mailinglists, howto's and what to do with
> the information -- for example where to store good code snipplets etc. I
> know it sounds hard and would require work with many people, especially
> the great persons who now maintain great sites at zope.org -- but also
> zopezen.oeg, zopelabs.com, zopenewbies etc.

Well... sure.  If you were to come up with a set of guidelines for
submitting documentation snipplets, it would be great.  I could then put it
up on the docs page.  Getting folks to follow those directions will be kinda
hard, but it'd be a start.

> It only requires some time and commitment -- which for most of us equals
> money. But count the numbers and tell me honestly, would you have any
> less -- or way much more, if our community for some parts would work
> like a well oiled machine. Atleast for me, Zope has been a great source
> of inspiration -- and honestly changed the way I see development... And
> I would be honoured to give something really valuable back.

Great!  I'm up for any suggestions.  Whatever we do, it needs to be
reasonably low-maintenance and fairly simple (and quick) to implement.

- C