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

[Martijn Faassen]

Hey Steve,

Thanks for recognizing a problem. I've actually been moderately happy
with the activities in grok-doc in the sense that at least *some*
activity has happened, but a lot more can definitely be done.

On Mon, Nov 16, 2009 at 2:29 AM, Steve Schmechel
<steveschmechel at yahoo.com> wrote:
[snip]
> 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.)

This won't magically fix the problem; the developers have only a
limited time too.
Unless people are willing to become developers to help with the documentation,
the documentation isn't going to rapidly improve. It's easier with
Repoze BFG as the project
and the documentation could grow at the same time, and there's simply
less to document.

> 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 think we should start rocking the boat technically too much at
this point. It risks scattering the documentation all over the place.
The community documentation to me looks a lot better than one would
find in the average wiki. (and I have no reason to suppose a wiki
would be more than average in our case).

How can we make life easier in the Plone context? Give a lot of people
approval rights in the workflow?

> 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.

Two things haven't been attempted yet, even though I've pointed out
both of them:

* from documentation not managed by the Grok project to the Grok
project. There are various pieces of great documentation produced and
published outside of our project. I've pointed out several. We should
actively bring these under our maintainership. This hasn't happened at
all as far as I know.

* from community documentation to official documentation. I've pointed
out over and over again we should take good quality documentation from
the community section into the officially managed documentation. This
will allow us to better keep the documentation in sync with the
releases. This hasn't happened at all either as far as I'm aware.

Once such a flow is established, we have a way to capture, preserve,
maintain and improve documentation. There *is* a lot of documentation
being produced, but it's just not captured and made more accessible.
It might also encourage contributions by others.

I don't know why nobody feels like they can do this.. It seems like
this would be only a moderate amount of work. So what's blocking that?

Regards,

Martijn