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

[Steve Schmechel]

While moving the documentation to SVN/Sphinx would be nice for version
control, it does not guarantee that it will be kept up to date and I
believe it would further limit the number of people willing and able to
help maintain it.

Most developers do not really like doing documentation.  Where I work we
use Mediawiki for any developer documentation that is not derived
directly from code.  Mainly because editing it is *fast*.  If you find a
mistake you don't contact someone to change it, you fix it yourself,
right now, and move on.  Anyone on the team can edit any document.  The
changes are easy to track and see.  If you don't like the change someone
else made, you simply roll it back.

I prefer a ReStructured Text solution like Grok uses.  However, it has
some issues:

1) It's too bad the document history is not available like in standard
Plone.  I always keep off-site backups of my work in case something gets
screwed up and I need to revert the content.

2) The current community documentation workflow is rather tedious.  I
can only edit my own documents.  Any errors I find in another document I
have to document on Launchpad and wait for the original author to
correct it or have a website manager fix it.  (I know Sebastian is
looking at ways to resolve this.)  

3) I can't believe ReST is still not the default formatting on the site.
Someone should really hack the Plone code so you don't have to remember
to pick it every time you edit a document.  

Even with those concerns, at least most people *can* contribute new
how-to's and tutorials in ReST or HTML, see the results immediately, and
maintain their own work.

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.

--- On Tue, 9/8/09, Martijn Faassen <faassen at startifact.com> wrote:
> 
> This is also why I'm in favor of people adding more documentation to
> the SVN documentation (that's generated with Sphinx). If people are
> too daunted checking into grok/doc I'd be happy to separate the 'doc'
> directory out into a separate grok-doc package or something like that.
> (one benefit of keeping it integrated is that it's clear which
> documentation belongs to which Grok version)
>