[ZDP] Re: DC's Zope Documentation Plan

[Amos Latteier]

Maik Roeder wrote:

> > Authoring and maintaining documentation must be
> > 1. possible
> >    -> Open up for contribution
> 
> Authors at Digital Creations should work together
> collaboratively with the Zope Community, sharing their
> ideas, as well as all existing and future documentation.

I completely agree. One of our main goals for Guide and References is to
open them completely so that the process for DC and community
contributions are the same.

> > Authoring and maintaining documentation must be
> > 2. easy
> >    -> Tools and processes to contribute
> 
> Not only should the contribution be easy, it should also
> be easy to change the tools that make this possible.
> The ZDP-Tools consists only of ZClasses. This way, adapting
> the tools to our needs has proven to be really easy,
> driving the will to contribute new documentation.

By choosing open standards for documentation, I hope that we can give
folks a choice of authoring tools.

> > Authoring and maintaining documentation must be
> > 3. rewarding
> >    -> Ownership and control
> >    -> Place in History
> 
> There should be a History Folder, a Changes Folder and Writer
> Folder as well as Maintainer Folders. In these all activities
> would be stored so it is easy to track who did what when
> to the documentation. I have been planning on these for
> the ZDP-Tools, but there is no code yet.

I completely agree. WRT References and Guides, chapters should include
author information about who has worked/is working on the chapter.

> > Authoring and maintaining documentation must be
> > 4. possible in many different ways
> >    -> contribution
> >    -> reviewing
> >    -> offering corrections
> >    -> offering examples
> 
> In the ZDP-Tools, the authors of documents can specify what
> there documents need. If they think a Reviewer is needed,
> they set the NeedsReviewer property. If they think Zopistas
> would only be confused by their material they would set
> the NeedsReaders property to 0, and ask for Writers by setting
> the NeedsWriters property. This circumvents the necessity
> to follow a formal step by step Review process, which would
> only hinder advancement. In the end, contributors should
> have a good feel of what state their information is in. If
> this would turn out not to be the case, then maybe rating
> content would be advisable as an additional measure.
> Bad rankings of documentation could point out weak doucments, which
> would then get the NeedsWriters property set below a certain
> threshold.

These annotations sound great. I think that we could probably do similar
things with the References and Guides. My guess is that each chapter
will have an owner(s) who has write access and is responsible for
keeping this status information up to date.

> > Authoring and maintaining documentation must be
> > 5. possible with different abilities
> >    -> technical
> >    -> writing
> 
> Contributions in the small should be possible just as contributions
> in the big. Therefore, in the ZDP-Tools a Maintainer has the
> right to set up a comments box, and ask for comments by setting
> the NeedsCommenters property. This allows for small annotations,
> and even for contributions. For bigger contributions, Maintainers
> set up DraftSubmissionFolder, which can be placed anywhere, and
> are then open for people to contribute larger documents.

This sounds like yet another area where you've thought things through
well.

> > Authoring and maintaining documentation must be
> > 6. non-redundant
> >    -> Catalog of existing documentation
> 
> This is easy all documentation is in one place. As it stands
> now, the ZDP and the Zope documentation are on different servers.

We should think about consolidating official Zope documentation onto the
ZDP server. However, there is additional documentation needing
cataloging including for example, the files in the Zope docs directory.

> > Zope API
> >   -> Ways to communicate knowledge of Zope core
> >   -> Provide API documentation for
> >      - Zope core
> >      - basic Zope objects
> 
> There must be conventions for documenting the API. I was looking
> at the PythonDoc and have already started the ZAPIDOC project.
> Please take notice of this project, and for further information
> have a look at it.

You should talk to Michel (michel@digicool.com) about this, he is
heading the interfaces project. I'll let him know.

> > Modularizing examples
> >    -> Examples could be authored separately
> >    -> Categorization
> >    -> Binding to Guides and References
> 
> There are Snippets in the ZDP-Tools, which I would encourage to reuse
> in any form of Documentation. I am thinking of global identifiers of
> Snippets and including them by id into the documents. Right now
> it would be practical to just drop a Snippet into a Draft for example,
> and reference it from the Draft. Snippet contributors should
> provide general descriptions of what the snippet is good for,
> and how it works.

I think that there is definite synergy between the snippets idea and the
need for examples in the Guides and References.

Thanks for your great ideas!

-Amos

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