[Zope] [ZDP] Announcing the Zope Documentation Project

Martijn Faassen M.Faassen@vet.uu.nl
Wed, 03 Mar 1999 11:52:32 +0100


Ken Manheimer wrote:
> 
> Martijn Faassen wrote:
> 
> > Hereby I announce in absolute adhoc anarchistic fashion the Zope
> > Documentation Project. The Zope Documentation Project aims to generate
> > documention on anything Zope.
> 
> Thank you, Martijn, you've made my day!  This is extremely cool.

I'm glad I made someone's day. :)

> As you might expect, here at digicool we're yearning to produce more and
> better documentation, and, as with other things, we want to have more
> time and energy to do it than we do.

It was getting obvious that this was so. You guys all did a great job,
and still are doing a great job, but the volume of questions and
documention requests has exploded in the mean time. Which is great, in
fact, of course, as it shows people are interested.

[snip]
 
> Some thoughts:
> 
>  - We would be happy to provide a mailing list or two for you all

This would be great! We probably don't want to be spread out too much so
one mailing list would be best (zdp@zope.org?). I also intend to make
regular announcements of ZDP's progress (and some advertising to get
people more involved in the project) on the main Zope list (or future
multiple main Zope lists :).

Right now though to keep the ball rolling I'll be using the normal list
to send out messages.   

>  - If it makes sense (logistically, for us as well as for you), we could
> host the FAQ stuff or whatever on zope.org.  This we'll have to discuss -
> both what all might want, and what we can safely and effectively do...

Zope.org would I think be the ZDP's favorite place to be hosted on, so
that'd be very nice. Your thoughts on how we could best arrange this
(who gets manage access to the place, if we develop in a branch we
export to you, or develop in there directly, or use FTP, or possibly
something else, etc) are welcome.

> (I've been thinking about requirements for a collaborative FAQ
> mechanism, which can be tricky if you want it to be available for
> contribution to the community in general, yet still remain organized
> enough for people to find what they're seeking.  An interesting
> problem...)

Independently (for local purposes) I've been thinking about making a FAQ
wizard product myself, but I got stranded somewhere in the beginning (my
laments I posted some time ago to the list :). But at least I've given
some thought to the design. Now Amos made one, and we can build on that.

The use of the tree tag is nice, but probably a simple list is more
useful in some cases (one can do a text search in it, for instance).
From my cursory glance at the management screens of the example, it
seems that it's not hard to produce that.

What would also be nice is some way to simply generate plain ascii text
versions of the FAQ as well, along with possibly some other versions. We
could also think about generating DocBook SGML (which then can be
converted in a lot of different formats with for instance the Linux
SGMLtools 2.0).

I haven't given too much thought to collaboration mechanisms. It would
be useful to have the ability to easily move questions around in the
list from one section to the other. My plan is to early on just get any
question/answer pairs we can come up with (from mining the mailing list,
documentation, and whatever people contribute). Later on we can then
organize these in categories, once the pattern becomes clear (likely
we'd have a DMTL section, for instance, and an installation section). If
there's flexibility in moving questions around the FAQ might be
developed more quickly. 

People could contribute question/answer pairs (or just questions) in
some 'contribution area' and the managers of the list can then edit
these and move them to the right sections of the list after doing so.
The contribution area should still be visible for everybody, so that
even the raw entries can be useful. I'm brainstorming right now, so
here's another idea: if someone sees a question in the 'contributed'
area that he knows the answer to, that person should be able to write in
an answer. Even with the already edited questions in the main list it
would be useful if people could leave comments ("I tried this but it
didn't work for such and such reason. But if I did this and that, I got
it working."). The editors can then later review all that's added and
integrate it into the main text.

Right now I intend to just assemble a big raw plaintext file (structured
text!), though; anyone can work with these. It's good to keep the
process moving.

Regards,

Martijn