[Grok-dev] Feedback on official documentation.
sylvain at infrae.com
Mon Nov 29 06:22:19 EST 2010
I have a bit of feedback on the official reference documentation.
The documentation that some directives are 'maybe required'. I like
that concept, it sounds
like 'maybe true' to me, which doesn't exists with a computer. I
think it will be worth
saying in which case they are required and not.
The notation grok.implements(*interfaces)() is confusing as well.
In a more general way the definition of all Grok directives are a
bit too abstract. Maybe
adding a glossay defining what is a Grok directive and so will
help. I did that
in the Silva documentation.
And all other relatively new decorator of grokcore.component are
- Zope schema. I found *nowhere* on the internet a official
documentation of available Zope
schema fields that can be used to create a form. It is a bit
frustrating for beginners
that you need to read the source of zope.schema to know it. The
only thing I saw that looks
vaguely to a documentation of those fields is the dexterity
documentation that contain a listing.
As well, maybe, I say maybe we can refactor the documentation into
parts, so that we can publish
a reference documentation for each grokcore package as well will be
nice (because I am linking
to the Grok documentation, but it is often a bit different how things
are used in Silva).
I can help with the documentation if need on my free time, and if
there is someone to
review my bad English.
Sylvain Viollon -- Infrae
t +31 10 243 7051 -- http://infrae.com
Hoevestraat 10 3033GC Rotterdam -- The Netherlands
More information about the Grok-dev