[ZDP] A profusion of documentation

Martijn Faassen M.Faassen@vet.uu.nl
Wed, 12 May 1999 19:29:39 +0200


Jimmie Houchin wrote:
[snip]
> 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 hasn't been settled, though we have thought about it all in the
context of CoolFAQ (stands for 'Collaborative FAQ' :), ZDP's pet
vaporware project. :) We need an action plan for that.

[snip how people has different strengths]

Much agreed.

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

Right, CoolDoc, I suppose (stands for Collaborative Documentation' :).
Hm. This gets a bit much for the ZDP. Let's focus on CoolFAQ, learn from
it, and see if we can apply our experience to the development of
CoolDoc. Right now, I think a simple start of organizing it on the ZDP
site is a good start. We can go from there (have people volunteer for
roles, such as editor, layout/formatting person, link/index maintainer).
Volunteer now! I volunteer as organizer of volunteers. :) Free free to
outvolunteer me on this at any time, however.
 
> 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.

Yes, this should be coordinated. The 'documentation index maintainer'
could keep a map of what's been documented (and what not).

Later on we can start codifying some of these tasks in Zope form.
 
> 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?

Good question. Any ideas are welcome. Want to volunteer as documentation
map maintainer (or whatever I called it before :), perhaps? A coherent,
consistent whole of everything is very important, I agree completely. We
can get there in phases, however.
 
> 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.

And rewritten and edited, in many cases, I think, which is more work.
But indeed, much the *information* we write down can be reused when we
start structuring information. Right now I'm interested in collecting
this information in a rough structure, so that we have a basis to work
from.
 
> What of the current documentation is available for reuse and building upon?
> What from the ZDP? What from Digital Creations?

Hm, documentation map person, where are you? :) (wait, there's a word
for this, librarian!)
 
> 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.

Well, the CoolFAQ idea is going in that same direction, but you're
widening things now. Possibly it fits in a CoolFAQ format, still,
however. We'll see.
 
> 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. :)

Sure, that was one of my reasons for helping to start it. The other is
of course that I learn a lot about Zope by doing this.
 
> Okay, enough 'hand waving'tm (Christopher Petrilli). :)
> My apologies if there is duplication of ideas here or discussion of issues
> already resolved.

No problem, it's good if ideas are shared by people in the group.

Regards,

Martijn