[Grok-doc] Future of the grok-doc list and community documentation in general

[Steve Schmechel]

It seems the majority of activity on the grok-doc list lately involves
administratively discarding list spam.  Maybe it is time to reconsider,
if Martijn was correct in advising against a second list and merge this
list back into the grok-dev list.

Further, I personally don't think the writing of documentation for Grok
is going to ever gain much sustained "community" momentum.  There just
does not seem to be a driving reason to do it.

In practical usage, Grok seems to be more of a library used to build an
application, than an application one uses directly to solve a problem.
I know this could be argued either way and technically Grok is a type of
framework, but looking at other frameworks, it seems that the existence
of narrative documentation depends either on an insistence by the
developers or is an eventual result of mass adoption.

I don't think mass adoption is very likely, as the pioneers of Grok
usage are all Zope/Plone veterans, who are able to get by with plain old
technical documentation (ApiDocs, generated class documentation, Doc
Tests, and the source code itself).  In addition, there are few
open-source applications that one can look at to see how Grok can be
used, and the ones that do exist (i.e. Dolmen) are not big enough to be
actively extended by other developers, so again there is no need to
provide narrative or how-to documentation.

I suspect that some of the best uses of Grok are contained in commercial
solutions written by the veterans.  It would then, be dependent on those
veterans deciding to write a separate how-to or tutorial (out of the
goodness of their heart), since others can't see or extend their work.
(Not knocking the ZPL, it is what it is.)

Maybe there will be enough usage in a big open source application like
Plone to one day reach critical mass, but the Plone/Grok.Five scenario
seems to cover only a portion of the possible uses of Grok.

The other option would be for the Grok developers to decide to make
narrative documentation a priority, and bring a selection of
documentation types into the "official documentation" and maintain it
throughout each release with the same priority as source code and tests.
(There was a suggestion along this line by Martijn.)

This would need to be more than just a beginner tutorial and some
isolated how-to's.  It would need to show how to use the framework in a
variety of ways, and should include working sample applications, which
are maintained with each release.  (If you want to see a good example,
take a look at the documentation for Repoze BFG.  There is technical and
narrative documentation along with sample applications, and it is kept
up-to-date as the framework code changes.  The effort is driven by the
developers, although users will suggest changes or improvements on the
mailing list.)

Community submissions could still be encouraged, but the contribution
process should be made much simpler.  I know the current Plone Help
based site attempts to manage the documentation based on version and
category and enforces an approval workflow for publication, but it is a
real pain to use.

A simple wiki would be much better.  Let users and reviewers comment and
actually correct the content, instead of having an external review
process that largely relies on the original author to come back and fix
things.  If some author really wants strict control of their work, there
are ways to handle that: keep the document external and put a link on
the wiki or get Zope SVN access and add it to the "Official
Documentation".

I don't mean to sound down on Grok or the community or any effort people
have put in so far, but I think we need to be realistic and practical.
Maintaining an unused list for a documentation process that provides
little incentive to contribute or maintain content, is not a good use of
time.  We'd be better off focusing people's limited time on testing the
Grok code and filing bug reports for the developers.

If other people have clever ideas about making the Grok documentation
better, let's have some discussion about it.

Insanity: doing the same thing over and over again and expecting
different results.  --Albert Einstein

Regards, 
Steve