One of the key problems is that a lot of excellent and helpful material exists but can't be easily found. For example, the mailing list has answers to a lot of questions, but it is hard to invent the right set of search terms to end up with the gold nuggets that actually talk about your problem. The same goes with the how-to's etc. Now you have only two ways: browse the subjects and guess, or do full text searches. Maybe a key thing in making the community contributions more useful could be to try to build more shared structure for the issues that are discussed, and start to use common descriptions for the issues. I am not sure how to do that...but I believe that contributions from both 1) those how know ZOPE and CMF well enough to put pieces in their most proper place and 2) those who know so little that they can't recognize what their problem really relates to have to come together in this - but maybe in a fashion that eventually is coordinated by one of those who is involved in the development of future directions. The common decsriptions need to have a good spectrum of levels of detail, so that if one knows exactly what one is talking about it can be specified, but at the same time it can be bound together with other issues in the same family. I think that in the first step, the mailing list messages could simply be further qualified with some keyphrases (one or more phrases which each contain one or more keywords that describe the issue in possibly increasing detail as in "workflow, customize", "xxx, x111, x222") by all, and maybe some of the more experienced ones could try to start the practice and establish some good examples of keyphrase structures. This annotation should of course take place already when messages are posted, but could be revised later in a database. The second component would be some kind of rating - so that those who find a snippet useful or wrong could indicate that (but I am not sure how to do this so that there would be some kind of quality control in the quality control). Eventually, a nice zope product can be written that makes it easy to organize and search these messages in an elegant way; this would also make a great database for structured, comprehensive, edited FAQ and book development. khk ...... At 21:06 -0500 1.4.2002, Chris McDonough wrote:
A while a ago there was discussion about the community stalling and the state of the documentation. As far as I can remember and see, there wasn't really any agreements or solutions what to do -- so I raise the question again -- and propably aim it to the people at Zope corp., what we -- noble users -- could do to help your work on documentation?
...
We have a great community -- that is unfortunately in very many pieces around the world. Nice thing is the diversity, but in some cases the effiency suffers. Should one turn into ZDP, Zope zen, zope newbies, zopelabs or search through the mailinglists? Huh?
Right. This is a hard problem. Good thing we're in the content management business. ;-)
Some options for improving the situation right now:
- try to find all the best "nuggets" in the form of HowTos and whatnot and try to fold these into the Books (ZB and DevGuide) in the form of new chapters or paragraphs.
- kickstart new.zope.org. (zzzz... ;-) New.zope.org has a lot of the features that we've been wanting like workflow for docs and products, if it ever gets out.
What I am suggesting is that together we create a certain set of methods of work, that we all will follow and help others to follow. These will include some etiquette on the mailinglists, howto's and what to do with the information -- for example where to store good code snipplets etc. I know it sounds hard and would require work with many people, especially the great persons who now maintain great sites at zope.org -- but also zopezen.oeg, zopelabs.com, zopenewbies etc.
Well... sure. If you were to come up with a set of guidelines for submitting documentation snipplets, it would be great. I could then put it up on the docs page. Getting folks to follow those directions will be kinda hard, but it'd be a start.