[ZDP] FYI: Documentation Futures

Amos Latteier Amos@digicool.com
Mon, 25 Oct 1999 14:30:01 -0400


Hi Folks,

I'm writing to let you know some of the things we're considering at DC
in terms of future documentation directions.

It is clear that DC is so far unable to keep up with the documentation
needs of the Zope community all by ourselves. The ZDP is a prime example
of how the Zope community has stepped up to address its own needs.

At DC, we're impressed by the ZDP and are considering opening some or
all of our current documentation (Zope Guides) up to the ZDP. 

We believe that this could result in:

  * Better quality documentation
  * More up to date documentation
  * More important presence of ZDP in Zope Community

We're imagining a scenario in which documentation is managed in CVS by
documentation champions. Perhaps docs would be owned on a chapter by
chapter basis, with community members owning chapters they cared about
and DC owning chapters that no one wants. DC could supply the initial
material, and the tools necessary to convert docs to various formats and
package them up for distribution and to work with a forthcoming on-line
help system.

Our general questions are:

  * Does this seem like a good general direction?
  * How do/don't the ZBook and ZQR projects fit into this project?
  * What more/else can DC do to empower the ZDP?
 
Our religious ;-) question is:

  * What format should the Guides be maintained in?

Right now we maintain the Guides in Framemaker, but probably this format
won't work well for the community since it is not free. Our initial
evaluation suggestions that DocBook is the most likely candidate since
it seems to be technically adequate and popular. Whatever format is
chosen, DC would be responsible for the initial conversion of the
existing Guides to this format.

Please let us know what you think. Your opinions count!

Thanks!

-Amos

--
Amos Latteier         mailto:amos@digicool.com
Digital Creations     http://www.digicool.com