[Grok-dev] Re: GrokDocs or: documentation for lazy developers
faassen at startifact.com
Fri Feb 29 07:54:07 EST 2008
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
* 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?
More information about the Grok-dev