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