[ZDP] A profusion of documentation

[Jimmie Houchin]

At 07:29 PM 5/12/99 +0200, Martijn Faassen wrote:
>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]

I think it would be reasonable as we venture down a documentation path that
we work up documentation formats for the various documentation forms. Or do
y'all (a valid word here in Texas) think that most of the document forms
I've mentioned are pretty much standalone and flexible per each document?

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

To a certain extent alot of this can happen right here in this group. 

I think we need to content providers/collectors/formatters for the various
subjects. When content is created or formatted for a specific form either
FAQ, Howto, User Guide, Tutorial or whatever then the eyes of the community
can provide content reviewing, proofreading, commentary and corrections for
the documents content maintainer. I think the primary thing here is that
everyone work from the same source, the same page so to speak.

Like right now, Zope has a CVS available for people to see the latest in
Zope source. This enables Zope to be built in a coordinated manner.
Everyones see the same content, works on the same content. This minimalizes
reinventing the wheel.

I don't know if we need explicit volunteers per se for the content
reviewing, proofreading, commentary and corrections. But it would be nice
to coordinate the content providers so we could divide and conquer.

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

I'll volunteer most anyway I can contribute.

[snip]

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

Yes, what I've stated is quite a bit broader than an FAQ.
But, I believe there is plenty of room for multiple types documentation.

[snip]

Jimmie Houchin