[Grok-dev] Re: GrokDocs or: documentation for lazy developers

[Martijn Faassen]

Hey Uli,

I really like that you're pushing this forward! I think it's a great 
idea to start reusing the toolset that Python uses to generate their 
documentation. Not only do we not have to invent the wheel ourselves, it 
can hopefully be used to make sure that our documentation looks 
"familiar" to Python programmers.

Do you think it would be reasonable to focus this work mainly on the 
reference? This way we can tell people to write tutorials and howtos and 
such on the site, and we generate a reference using this. Looking at 
python.org documentation, a lot of this is actually reference 
documentation (especially library), so I think we could potentially have 
a lot too, especially if we venture out in somehow documenting relevant 
parts of the Zope 3 API itself.

Then again, if the main tutorial fits better into this stuff, I'd be 
happy to work with that. The main tutorial is an exception anyway to 
most documentation, as we aim to maintain this in the filesystem 
definitely, unlike most of our other documentation.

Anyway, my aim is to come up with some clear and short guideline that we 
can use to determine where documentation should be going. Something like 
this perhaps:

* grok.zope.org for everything people want to contribute

* unless it's the reference or main tutorial, which are maintained using
   the filesystem-based toolset.

What do you think?

Regards,

Martijn