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

[Sebastian Ware]

I almost sat down to answer the post, but decided to finish off adding  
the Poller Tutorial instead :)

Yeah, liberal editing rights off the bat would be great. I get a bit  
frustrated by Plone, but I can live with it.

-Could edits to published content in Plone be mailed to grok-doc?

-Should we stop tracking content in Launchpad?

We need an editor in chief who is in charge of all the official docs.  
He should be your right hand man Martijn. I know I keep bickering  
about this, but we need someone drawing the map. Personally I stir up  
too much controversy, but someone who understands learning and the  
writing process and has your respect and the respect of the community.

Anyhow, don't worry about low activity on the grok-doc list. It is as  
much a reminder of the fact that we still have a lot of work to do to  
get the community docs maintenance working.

Couldn't someone write a small webapp that could make api-docs etc.  
more accesible?

Mvh Sebastian


16 nov 2009 kl. 08.50 skrev 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
> _______________________________________________
> grok-doc mailing list
> grok-doc at zope.org
> https://mail.zope.org/mailman/listinfo/grok-doc