[ZDP] A profusion of documentation

[Jimmie Houchin]

Hello,

I've been a long time subscriber to the bobo, zope lists. Until recently I
did not have a working implementation of Zope from which to develop since
there is no Mac version. I added LinuxPPC to my Mac and resolved that
issue. :)

A few comments:

I think it would be nice if we could settle on a consistent format for the
development of documentation so that there is a consistent look and feel to
the end user of the documentation. If this has been settled my apologies, I
didn't see it. If this is going to be a structured text format, howabout a
template from which to work.

It would also be nice if there was a system in place for members of this
project to be able to contribute 'diffs' of the documentation so that they
could be easily reviewed and applied by the document maintainer. All of us
here have different skills we bring to the table. Some of us the skills are
technical knowledge. Some of us have better writing skills. Some of us have
good editing skills. For some of us English is not the native language. (No
offense intended. I am astounded at how well many of you who do not speak
English as a native language communicate with those of us who do.
Personally, I only know English.) Also, it is always easier to edit what
you did not personally write. The errors are easier to see.

It would be nice if a system was in place to facilitate the application of
each of our skills to a common piece of text and applying the 'diffs' to
create the final product. 

Can we coordinate the documentation effort so that primary efforts are not
duplicated. When I say primary efforts I am not necessarily speaking of
reviewing, commenting, proofreading and editing. I am mainly refering to
original/semi-original content creation.

With the Zen of Zope outline by Michel we have a good basis for subjects
for documentation. There is an abundance of documentation forms from which
to choose, Tutorials, FAQs, User Guides, Manuals, Howtos, etc. What all
forms do we wish to put this in? How should we break down the subjects into
each of the forms we choose?

Just as in code reuse, documentation reuse would be good. Much of the
material in one form can be reformated to be placed into another form.

What of the current documentation is available for reuse and building upon?
What from the ZDP? What from Digital Creations?

There is alot of good material available which simply could use some
updating as Zope matures and changes. If some of it is available for
building differently formatted materials that would be great.

It would be nice to see this project help Digital Creations with some of
their load, so that they can spend their time working on the best web app
tool available. :)

Okay, enough 'hand waving'tm (Christopher Petrilli). :)
My apologies if there is duplication of ideas here or discussion of issues
already resolved.

Time to find where I can contribute. :)

Jimmie Houchin



At 02:33 PM 5/12/99 +0200, Martijn Faassen wrote:
>Hi there,
>
>I'm seeing the ZDP project is generating a profusion of documentation.
>As mentioned before, we should put this documentation on a webserver.
>I'd naturally propose zdp.zope.org for this.
>
>If someone feels the calling to:
>
>a) Collect the documentation that we have
> 
>b) Make a relatively simple organization on the ZDP website. Keep this
>simple initially.
>
>c) Put the documents on the website
>
>he or she can contact me for a ZDP zope login. If nobody volunteers
>until next week or so, I'll volunteer myself. :) Note that I will only
>check my mail irregularly later on this week, so you people might want
>to contact Pavlos or Martijn Pieters instead, who can provide you with
>access to the ZDP server as well. If they're around. :)
>
>Once we've got it all collected we have some more overview and can think
>about extending and improving it (as well as editing and restructuring).
>I'm vaguely thinking about a Zen of Zope webbook, with many links to
>examples, and each section should have a short 'Zen', such as:
>
>Zen: Web sites are turning from magazine style publishing of pages into
>complex interactive applications. To maintain and develop these web
>applications a web application server can obviously help.
>
>Zen: Take advantage of acquisition! Acquisition has powerful
>consequences for the structuring of your site.
>
>Minor Zen: Directories are acquired too!
>
>Or whatever. Of course my Zens aren't very deep yet, but it's a start.
>
>I expect we have a lot of work ahead of us to make the documentation as
>helpful, complete, consistent and readable as possible, but with these
>contributions we're leaping forwards.
>
>Any discussion (from volunteers) on how what documentation to put on the
>zdp.zope.org server, and what its initial simple structure should look
>like should, as always, go to this list. Now I'll go back to reading all
>your docs. :)
>
>Regards,
>
>Martijn