[Grok-dev] Feedback on official documentation.

[Sylvain VIOLLON]

Hello,

   I have a bit of feedback on the official reference documentation.

   - grok.Adapter:

     http://grok.zope.org/doc/1.2.1/reference/components.html?highlight=view#grok.Adapter

     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.

   - grok.provider

     And all other relatively new decorator of grokcore.component are
     all missing.

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

   Regards,

   Sylvain

-- 
Sylvain Viollon -- Infrae
t +31 10 243 7051 -- http://infrae.com
Hoevestraat 10 3033GC Rotterdam -- The Netherlands