[Grok-dev] documentation

[Martijn Faassen]

Hi there,

We need to do some work on getting the new official documentation 
integrated into the main site soon. Especially since Philipp already 
announced it in his blog. :)

I think it's important that people can get from 
grok.zope.org/documentation to the "official documentation" section. I 
think we can do this by simply replacing some links in the plone site to 
  the 'current' section in the new site. (especially the tutorial and 
the developer's notes).

We should also make such links in our future release announcements.

There's a section called "What's new in Grok?" in the new documentation 
that's a misnomer, as it only contains our incompatible upgrade 
documentation and doesn't actually include what's new in Grok. We either 
make "What's new in Grok?" link to our change log (with perhaps a link 
to this upgrade document) and make a new link "Grok upgrade notes" on 
the main page, or we just replace this with "Grok upgrade notes". I just 
want to reemphasize what we cannot get way with calling this "what 
changed" and such.

We also need a good link back to our community documentation. Right now 
in the official documentation that's a tab on the top. I'm not convinced 
by these tabs - they're easy to miss. It'd be nicer if such a "Community 
documentation" link appeared among the other links on the page.

I think 'naming conventions' is probably not important enough to have 
its own heading. It'd be nice if that were in some subsection on 
managing and releasing the development of Grok itself...

As to when this stuff should happen, I think all this stuff can happen 
today. I think it's fine if we publish the unfinished 0.14 documentation 
as the 'current' Grok documentation and link grok.zope.org over to use 
it right away. Philipp is right that it needs some exposure.

Regards,

Martijn