[ZDP] Re: DC's Zope Documentation Plan

[Maik Roeder]

Hi !


Great to have you at DC join our documentation efforts !

Here are my comments:

> 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.

> 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.

> 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.

> 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.

> 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.

> 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.

> Authoring and maintaining documentation must be
> 7. directed
>    -> Awareness of what areas most need work

There are many awareness services in the ZDP-Tools, and more
will be added. Activity searches and searches for what documents
need what kind of role are available. Additionally we are
planning to collect Requests for documentation, so we will
know what needs our readers have.

> 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.

> Online Help System
>  -> context-sensitive help for Zope users
>  -> Help for ZClass and Python Products
>  -> Tools and procedures to document extensions

In the ZDP-Tools I have included the possibility to jump directly to
the code of the ZClasses, it's base classes and a flat list of all
methods, which is really useful, making programming very productive.
In addition, it would be great to have ways of directly jumping to
the documentation of the code from the code. For this purpose I have
created ProductDocumentationFolders and ZClassDocumentationFolders.
Links to these will soon be added.

> 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.

> Searchable Mailing List Archive
>    - capturing information
>    - reuse information

It would be extremely useful to be able to digest the Zope mailing
lists inside Zope. With this I mean uploading the Posts into Zope,
selecting portions of it and moving it around the ZDP. Postings
can become Questions, FAQ-Answers, Drafts, How-To's or whatever.
This would include adding the original author to a History ZClass,
and a link back to the original post.

Greetings,

Maik Röder