[Zope3-dev] Z3 documentation

[Stephan Richter]

On Tuesday 01 April 2003 15:38, Garrett Smith wrote:
> Thanks Stephan,
>
> Would it be desirable to have documentation in a format that is akin to
> MSDN, which is bookish but is still usable as a reference? I think
> having a solid top-down structure (i.e. a good table of contents) and
> carefully defined help topics is an excellent way to manage non-trivial
> documentation projects.

I tried to structure the *existing* documention as good as I could in the 
Documentation Wiki. In my experience it is totally useless in Free Software 
communities (I learned that very early on when I joined the ZDP in 1999 ;-) 
to create a lengthy documentation outline without content, because everyone 
joining the documentation project has his/her own ideas on what s/he wants to 
work on.

> There are a few goals that I think are important:
>
>  - Ease of use - readers should not have to be terribly clever or
> patient to find answers to questions.

I think Wikis are perfect for this, since words are automatically linked, if 
there is a Wiki page with the same name.

>  - Sensible progression - the docs should have a good starting point and
> move through topics as a reader might expect.

Right, this is the goal of the programmer's tutorial and partially that of the 
Cookbook. However, not all documentation is suitable for this approach.

>  - Quality transparency - readers should know the quality level of a
> help topic without having to read it. This might be similar to the
> Wiki's status badges, but would likely cover things like percent
> complete, readability, comprehensiveness, etc.

Well, the Wiki status badges are just a rough marker. I often add an 
explanatory statement to the status. So we do that already.

> - KISS - capture relevant documentation as it exists and fill in missing
> topics, but avoid getting bogged down with things that no one needs.

I think that most of our documentation is very practice oriented. The 
programmer's tutorial is used for teaching people about Zope 3, the 'Hello 
Package' is a hands on example and the Cookbook's recipe suggestions came out 
of the real development needs as well.

> Some questions:
>
> 1. Is a Wiki still the most suitable format, at this point, for help?
> What about docbook? Another format? I would be reticent to use anything
> that could not be managed under SCM tools.

Wikis are the best for many reasons (wow this list became much longer than 
intended ;-):

1. Active developers are subscribed to the change-log mailing list for Wikis, 
so they tend to comment quickly on new content.

2. It is better than CVS-based docs, since the Email messages are easier to 
read.

3. Everyone has access to Wikis and can therefore contribute without much 
hassle.

4. Wikis allow us to create all different kinds of document structures 
(general graphs), not only simple trees.

5. Wikis maximize the reuse of existing documentation due to automatic 
linking.

6. They are already used by the Zope 3 development community and people are 
familiar with them.

7. I certainly do not want to learn yet another tool; I have enough troubles 
keeping track of the Zope 3 technologies, so I do not want to learn 
additional ones. Furthermore, people will have to download new tools for 
other formats.

8. It will be easy to export the Wiki texts to other formats, such as Docbook 
and/or LaTex.

9. Wikis are in place, so that we can be productive right away and do not need 
to develop documentation tools first.

> 2. What is the primary target audience? E.g. Zope2 users? Zope2
> developers? General readers outside the Zope community? While well
> designed docs can certainly address the needs of multiple groups, it's
> generally helpful to identify a primary target.

Currently, we write mainly documentation for the component developer (Python 
Programmer) and the Site Developer. I think that the cookbook, programmer 
tutorial as well as most of the online documentation is geared towards this 
group.

However, the documentation group should not limit itself to this audience. In 
the Documentation Wikis, I tried to list the other target audiences and 
outline what type of documentation is needed for them.

> 3. How much bandwidth is available in the development community for
> fielding questions about existing help and filling in pieces? I can do
> my best to piece together what's available from various Wikis, readmes,
> mail archives, etc. but I (others?) will undoubtedly have questions
> along the way.

Well, there is always this Zope3-Dev mailing list and the #zope3-dev IRC 
channel on irc.freenode.net. All active developers will respond to your 
questions there. Furthermore, most developers also provide low-level 
documentation in the CVS and often comment on Wiki changes, which is really 
nice.

I hope this helps. To get your feet wet, you could start out by writing 
OnlineHelp documentation (CVS plain text files for now), since this is fairly 
high-level. If you like, I can get you setup.

Regards,
Stephan
--
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training