[Grok-dev] community documentation deployed on grok.zope.org

[Uli Fouquet]

Hi JW,

Jan-Wijbrand Kolman wrote:

> With considerable latency, lo and behold: the community documentation is 
> being deployed on grok.zope.org:
> 
>    http://grok.zope.org/doc/community/

Great! Thanks a lot to all who helped yet!

> It is updated hourly.
> 
> A couple of remarks from my perspective:
> 
> * Somehow the "generated on"-timestamp is missing from the index page.
>    I think it should be there, but I do not know why it isn't.

That's really mysterious. The layout at least should insert the
`last_updated` value. I currently have no clue.

> * The index page suggests this documentation is for the Grok-1.2
>    release. I'm not sure we can claim that for each document. Maybe we
>    should label each document with a target version.

Strictly speaking, the documentation might have a version of its own,
but having that displayed could be very confusing for readers.

> * We might want to define a document template for the documentation,
>    including the aforementioned target version, author information, etc.

One could simply add markup like this on every page::

  :Author: JW <jw at grokheaven.org>
  :Version: This tutorial is tested for Grok versions 1.0-1.2

I guess this is easier to handle and maintain than complicated template
magic.

> * There's a navigation menu at the top in the form of several tabs. The
>    links in there are not correct, but I actually wonder whether we
>    should keep the links there in the first place.

IMO all links except the last two ones ("What's changed" and "Grok
Community Documentation") should stay. One can discuss, however, whether
the tutorial and developer notes should be shipped with the reference
rather than with the the community docs.

> * I removed the latex and PDF rendering parts from the build script.
>    They didn't seem to work at this moment. At least not on the
>    grok.zope.org host.

Can you tell what went wrong? Most people with a more recent LaTeX
install should be able to build PDFs. At least it works here.

Thanks for all your efforts!

Best regards,

-- 
Uli

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Dies ist ein digital signierter Nachrichtenteil
Url : http://mail.zope.org/pipermail/grok-dev/attachments/20110110/6fc96d54/attachment.bin