[Zope] Re: [ZDP] Documentation

[Andreas Kostyrka]

On Mon, 16 Aug 1999, Stephan Richter wrote:

[chop]
> The Solution:
> ---------
> The solution is to transfer (download?) the knowledge from the Zopster's heads
> down into screen and print media. Together we can make it happen. One guy
> certainly cannot do the documentation himself.
> 
> How do we bring the solution to reality? I wrote a rather lengthy letter to
> Paul Everitt this weekend.describing some of the tools which could help us to
> do this. For example I suggested to have a FAQ that is built by the community,
> by providing the Zopsters tools to add questions and answers directly to the
> FAQ. This way the editor only needs to check for grammar and spelling in the
> FAQs.
Well, there might be editors, but the FAQ as such should not be moderated.
One thing is still left out, how to control excesses from anonymous
web users.
A twofold strategy could be used:
1.) add the needed information on editing to the monthly mailman reminder.
    And don't answer questions asking for the information. This way
    casual vandals are kept out.
2.) Editors do have Undo capabilities :)

> Another way would be to build some kind of Reference Manual, which lists all
> DTML tags, Products, DB Adapters and other objects. The community can then add
Well, the documentation for DTML tags, etc. should be contained in the
source. It's the only way to keep the documentation update. If
documentation strings are not enough, than special comments that could be
extracted automatically should be added.
> descriptions and attributes, methods and so on to make the Reference complete. 
This will never work. Documentation of this kind must be part of the
source, or it will always trail behind the developement significantly.

> When and how to Start:
> ----------------
> We need to start now. I would be willing to take the task of developing a tool
> that will allow us to create FAQs and the Reference manual. I appreciate any
> help I can get by providing me with comments and suggestions of how the tool
> should look like and how it should perform. If anyone wants to share the effort
> with me PLEASE contact me.
Well, you could start out with Confera ;)
> If Digital Creations already started a tool like that please contact me also.

One thing, that I didn't get is, which tool is being used by ZDP?
SGML? LaTeX? some closedsource word processor?

Andreas
--
Andreas Kostyrka                     | andreas@mtg.co.at
phone: +43/1/7070750                 | phone: +43/676/4091256   
MTG Handelsges.m.b.H.                | fax:   +43/1/7065299
Raiffeisenstr. 16/9                  | 2320 Zwoelfaxing AUSTRIA