[Grok-dev] Grok & the lack of good documentation
faassen at startifact.com
Wed Sep 9 08:19:04 EDT 2009
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
Django seems to do it with Sphinx and SVN:
Django has a reputation for excellent documentation.
More information about the Grok-dev