[Zope] Use the source Luke -- what could be done to help documentation process? Request for comments!

[Kari-Hans Kommonen]

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.