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

[Uli Fouquet]

Hi Martijn,

Martijn Faassen wrote:

> 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.

Yeah, that sounds great! We have the KGS now and if it is possible to
setup apidoc.zope.org, then it is also possible to do a Zope 3
documentation with sphinx. This, naturally, needs a lot of work but with
sphinx there would be a clear way to go :-)

> 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.

Good point! This is a good time to make the responsibilities clear.

> 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?

Excellent! Let's do it this way! 

I assume, it is okay to keep some basic howtos etc. in the filesystem
(copies from the website with grok.zope.org as authorative source)? If
this is too confusing, then we should skip even these.

Kind regards,

-- 
Uli