[Grok-dev] Grok & the lack of good documentation

[Martijn Faassen]

Hey,

Steve Schmechel wrote:
> For official documentation, one would need to acquire Zope SVN commit
> access.  You would be strictly limited ReST content.  You would need to
> configure and run Sphinx on your local machine if you want to preview
> your work.  Otherwise, you commit the code and wait for Sphinx to be run
> on the server (nightly? only with releases?) to see the result.  
>
> I think that would scare away all but the most ardent document writers.

It's true that these are significant obstacles, so I definitely agree 
this shouldn't be the *only* route to documentation. The CMS is fine for 
collecting all kinds of contributions of a wide range.

But I also think we should consider it as a route to *quality*, 
well-maintained documentation that runs in synch with a release. We can 
collect a lot of documentation through the CMS, but integrating it and 
maintaining it seems to me easier with a tool like Sphinx.

Installing and running Sphinx isn't difficult - if you check out Grok 
now and run the buildout, there'll be a script bin/grokdocs2html that 
runs it all for you.

Getting SVN access is indeed a bit of an obstacle, though mostly a 
psychological one.

Django seems to do it with Sphinx and SVN:

http://docs.djangoproject.com/en/dev/internals/documentation/#internals-documentation

Django has a reputation for excellent documentation.

Regards,

Martijn