[Grok-dev] Reference documentation and workflow

[Fred van Dijk]

Hello Grokkers,

At the sprint Uli Fouqet has finished and checked into trunk the
autogeneration of the documentation in Grok to html. It would be great
toto have this documentation on the Grok website.

However, there's already a Plone Help Center (PHC) documentation
section on the website with howto's and tutorials. We (Kamon & me at
the Grokkerdam sprint) feel that both have a place in the
documentation story and would like to suggest the following
'workflow':

The svn generated documentation will be the official reference manual.
You need svn access for it and the grok core developers can maintain
this part, include suggestions from others and keep it sane. The
reference manual contains the grok reference and the official
'beginners' tutorial, but no other tutorials or howto's.

Hopefully a rewrite rule can be set up on the website and make
http://grok.zope.org/reference a link to the reference manual. Maybe
even http://grok.zope.org/reference/0.12 and a /latest to accomodate
for multiple versions.

The PHC on the grok.zope.org can contain tutorials, howto's and other
user contributed content. If people want to help out with
documentation we can give them access to the PHC, without them needing
svn access to svn.zope.org. If material on the PHC is deemed genenal
enough, those with svn access can include it in the reference
documentation.

One thing we should be cautious about though is that half finished or
'in progress' documentation should not show up in the autogenerated
html on the website. Either there could be a separate 'in progres'
directory in svn, writers can put their stuff on the PHC first, or we
only put the 0.1X and further official released versions on the
website.

Your feedback & suggestions please.

Greetings,

Fred van Dijk