RE: [Zope] [ZDP] Announcing the Zope Documentation Project
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. 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. This kind of effort from you, and from anyone else who can help, is *severely* appreciated. I know i'll be participating - question is, besides scraping together the time we can, how else can digicool help? Some thoughts, below...
The Zope Documentation Project needs people who wants to help. It needs these people to get organized.
To get focused, I propose the ZDP's initial project is to provide FAQs on various Zope topics. We can mine the mailing list for good questions and answers.
The ZDP asks everybody to contribute. Right now we need everything. :) We need questions and answers, and we need to categorize these in separate FAQ sections. We need Zope webspace somewhere to put up the FAQ, I assume using the FAQ product. We need to develop the FAQ product further, if necessary. We need whatever you can think of.
The prime mean of communications for the ZDP is the Zope mailing list, until further notice. I suggest that to keep the mailing list somewhat organized we prepend our mailing list subjects with '[ZDP]'. If somebody has a better way, we'll do it a better way.
Some thoughts: - We would be happy to provide a mailing list or two for you all - 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... (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...)
Note that while I'm sending out this message, I'm not anything
official.
I'm just attempting to get the ball rolling.
*nudges the ball*
Yay! Ken klm@digicool.com
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
On Wed, 3 Mar 1999, Martijn Faassen wrote:
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 would love to see this feature (generating DocBook SGML). I thought about something like this myself (for my howto), but I just don't have the time at the moment. I could probably find enough time to help out a little though. --- John Eikenberry [jae@kavi.com - http://taos.kavi.com/~jae/] ______________________________________________________________ "A society that will trade a little liberty for a little order will deserve neither and lose both." --B. Franklin
John Eikenberry wrote:
On Wed, 3 Mar 1999, Martijn Faassen wrote:
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 would love to see this feature (generating DocBook SGML). I thought about something like this myself (for my howto), but I just don't have the time at the moment. I could probably find enough time to help out a little though.
I'm randomly assuming here you know more about DocBook SGML than I do, so here I'm involuntarily inofficially but you can back out of it immediately appointing you the ZDP DocBook SGML expert. :) I think perhaps the first thing you could do is get together with people in the Latex thread for docs; they seem to have come up with it independently. I know even less Latex than SGML and SGML seems a closer fit with the XML-ish direction the web's taking, so my question would be to point out the advantages of SGML to everybody. Regards and thanks in advance, Martijn
participants (3)
-
John Eikenberry -
Ken Manheimer -
Martijn Faassen