FAQ section for Grok?

[Danny Navarro-2]

Hi,

Fernando Correa just explained me what is a grokker and what does  
grokking mean (in Grok). I thought it would be useful to add the  
explanations to a FAQ section at http://grok.zope.org

Upon your feedback I can start publishing the following questions:

- What is a Grok directive?
A Grok directive is a snippet of code meant to be interpreted by a  
grokker. [Link to Grok directives reference grok 0.14dev?]

- What is a grokker?
A grokker is a component that extracts grok directives from Python  
code so that the components are coupled by Zope component machinery  
(site manager?). You don't need to learn how to write grokkers unless  
you want to extend Grok itself.

- What does someone mean when claiming that a component has been  
grokked?
It means that the grokker has acted on the component and has been  
configured by Zope machinery. It's one of the most frequent words you  
will read from Grok developers if you follow Grok-dev mailing list.

- What are the megrok packages about?
The packages that are under megrok namespace package are non-essential  
Grok packages that extend the basic functionality of Grok. Some of  
them integrate different Zope 3 packages into an easier to use Grok  
package which follows Grok conventions for sensible configuration.

- What are the grokcore packages?
These are packages that actually make Grok. You don't need to deal  
with them unless you want to understand how Grok works internally.

Actually I have been compiling a very long list of questions at the  
same time I was learning Grok and Zope3, but instead of sending them  
all, I can start publishing FAQs gradually as I learn more about Grok  
and get feedback from people who can ensure my naive answers are  
correct.

Regards,

Danny
_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Martijn Faassen-2]

Hi there,

A FAQ section on grok.zope.org would be very good to have! I heard
earlier that Peter Bengtsson was working on something like this as well;
perhaps you could contact him and ask him what the status is? (but don't
wait forever for him; just go ahead and do it)

Danny Navarro wrote:
> Fernando Correa just explained me what is a grokker and what does
> Upon your feedback I can start publishing the following questions:

I've put in my versions below.

> - What is a Grok directive?
> A Grok directive is a snippet of code meant to be interpreted by a
> grokker. [Link to Grok directives reference grok 0.14dev?]

[I wouldn't use 'snippet of code']

A Grok directive is a class or module-level annotation that looks like this:

   grok.foo('information')

If in a class, it annotates the class with extra information used to
configure the class. If in a module, it annotates the module with this
extra information. A module-level directive can be used as the default
for all classes, if it can also occur in a class itself.

Directives are often optional; if they are left out the default value
for that directive kicks in. The ``grok.require`` directive for example
has as its default ``zope.Public``, meaning views are public by default.

Grok directives are interpreted by a grokker.

> - What is a grokker?
> A grokker is a component that extracts grok directives from Python code
> so that the components are coupled by Zope component machinery (site
> manager?). You don't need to learn how to write grokkers unless you want
> to extend Grok itself.

A grokker is a component that configures a class, module or instance
with Grok. It uses annotations made by directives to determine the
details of this confirmation. Configuration often entails the
registration of a class with the Zope Component Architecture (ZCA); an
adapter is for instance registered with the ZCA by what it adapts and
what interface it adapts to.

You don't need to learn how to write grokkers unless you want to extend
Grok itself with new configuration behavior.

> - What does someone mean when claiming that a component has been grokked?
> It means that the grokker has acted on the component and has been
> configured by Zope machinery. It's one of the most frequent words you
> will read from Grok developers if you follow Grok-dev mailing list.

It means that any relevant grokkers have acted on the component and the
component has been configured.

> - What are the megrok packages about?
> The packages that are under megrok namespace package are non-essential
> Grok packages that extend the basic functionality of Grok. Some of them
> integrate different Zope 3 packages into an easier to use Grok package
> which follows Grok conventions for sensible configuration.

[No amendments here. :)]

> - What are the grokcore packages?
> These are packages that actually make Grok. You don't need to deal with
> them unless you want to understand how Grok works internally.
>

These are packages that implement certain features in Grok itself. You
don't need to deal with them unless you want to understand how Grok
works internally, or if you want to use bits of Grok outside of Grok
itself, for instance in a non-Grok Zope 3 application or in a Zope 2
setting.

> Actually I have been compiling a very long list of questions at the same
> time I was learning Grok and Zope3, but instead of sending them all, I
> can start publishing FAQs gradually as I learn more about Grok and get
> feedback from people who can ensure my naive answers are correct.

I think a FAQ is a great initiative! It's definitely another very
helpful way to help people learn Grok and understand discussions about it.

I think it'd be good if you posted a few more questions & answers you
have to the mailing list. I'll be happy to write my answers. Even though
I did write a lot of my own answers here, your answers were very helpful
to me in writing my own, and it's also interesting to see what other
people's answers are, so please do continue writing them (unless you
really don't know the answer of course).

I also invite others to submit answers to the questions you ask here; we
can combine multiple answers into a good FAQ answer that we can then
publish to the site.

Regards,

Martijn

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Baiju M-3]

----- "Martijn Faassen" <faassen@...> wrote:
> Hi there,
>
> A FAQ section on grok.zope.org would be very good to have!

An FAQ for Grok would be really great.  But I have one suggestion,
please read this article and go through some good FAQs:
http://svnbook.red-bean.com/nightly/en/svn.foreword.html

Regards,
Baiju M
_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Peter Bengtsson]

2008/8/7 Martijn Faassen <faassen@...>:
> Hi there,
>
> A FAQ section on grok.zope.org would be very good to have! I heard earlier
> that Peter Bengtsson was working on something like this as well; perhaps you
> could contact him and ask him what the status is? (but don't wait forever
> for him; just go ahead and do it)
>
Peter was working on a Glossary that's even checked in into svn but
got lazy and drifted into something else.
At the moment he's working on a Grok cookbook which'll kick ass but
won't be ready for another month.

Please Danny, start the work on a nice FAQ. I'm sure lots of people
will be willing to help you.

> Danny Navarro wrote:
>>
>> Fernando Correa just explained me what is a grokker and what does Upon
>> your feedback I can start publishing the following questions:
>
> I've put in my versions below.
>
>> - What is a Grok directive?
>> A Grok directive is a snippet of code meant to be interpreted by a
>> grokker. [Link to Grok directives reference grok 0.14dev?]
>
> [I wouldn't use 'snippet of code']
>
> A Grok directive is a class or module-level annotation that looks like this:
>
>  grok.foo('information')
>
> If in a class, it annotates the class with extra information used to
> configure the class. If in a module, it annotates the module with this extra
> information. A module-level directive can be used as the default for all
> classes, if it can also occur in a class itself.
>
> Directives are often optional; if they are left out the default value for
> that directive kicks in. The ``grok.require`` directive for example has as
> its default ``zope.Public``, meaning views are public by default.
>
> Grok directives are interpreted by a grokker.
>
>> - What is a grokker?
>> A grokker is a component that extracts grok directives from Python code so
>> that the components are coupled by Zope component machinery (site manager?).
>> You don't need to learn how to write grokkers unless you want to extend Grok
>> itself.
>
> A grokker is a component that configures a class, module or instance with
> Grok. It uses annotations made by directives to determine the details of
> this confirmation. Configuration often entails the registration of a class
> with the Zope Component Architecture (ZCA); an adapter is for instance
> registered with the ZCA by what it adapts and what interface it adapts to.
>
> You don't need to learn how to write grokkers unless you want to extend Grok
> itself with new configuration behavior.
>
>> - What does someone mean when claiming that a component has been grokked?
>> It means that the grokker has acted on the component and has been
>> configured by Zope machinery. It's one of the most frequent words you will
>> read from Grok developers if you follow Grok-dev mailing list.
>
> It means that any relevant grokkers have acted on the component and the
> component has been configured.
>
>> - What are the megrok packages about?
>> The packages that are under megrok namespace package are non-essential
>> Grok packages that extend the basic functionality of Grok. Some of them
>> integrate different Zope 3 packages into an easier to use Grok package which
>> follows Grok conventions for sensible configuration.
>
> [No amendments here. :)]
>
>> - What are the grokcore packages?
>> These are packages that actually make Grok. You don't need to deal with
>> them unless you want to understand how Grok works internally.
>>
>
> These are packages that implement certain features in Grok itself. You don't
> need to deal with them unless you want to understand how Grok works
> internally, or if you want to use bits of Grok outside of Grok itself, for
> instance in a non-Grok Zope 3 application or in a Zope 2 setting.
>
>> Actually I have been compiling a very long list of questions at the same
>> time I was learning Grok and Zope3, but instead of sending them all, I can
>> start publishing FAQs gradually as I learn more about Grok and get feedback
>> from people who can ensure my naive answers are correct.
>
> I think a FAQ is a great initiative! It's definitely another very helpful
> way to help people learn Grok and understand discussions about it.
>
> I think it'd be good if you posted a few more questions & answers you have
> to the mailing list. I'll be happy to write my answers. Even though I did
> write a lot of my own answers here, your answers were very helpful to me in
> writing my own, and it's also interesting to see what other people's answers
> are, so please do continue writing them (unless you really don't know the
> answer of course).
>
> I also invite others to submit answers to the questions you ask here; we can
> combine multiple answers into a good FAQ answer that we can then publish to
> the site.
>
> Regards,
>
> Martijn
>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev@...
> http://mail.zope.org/mailman/listinfo/grok-dev
>

--
Peter Bengtsson,
work www.fry-it.com
home www.peterbe.com
hobby www.issuetrackerproduct.com
_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Peter Bengtsson]

Danny,
I actually got started on something but it's too unfinish to be worth
sending to you.
What I had in mind was a very simple Grok app which would be like a
wiki where anybody could add and edit entries and these would then be
ordered and exported to a .rst file into the svn trunk of Grok itself.
Perhaps you can do that and I can help if I find the time.

2008/8/7 Martijn Faassen <faassen@...>:

> Hi there,
>
> A FAQ section on grok.zope.org would be very good to have! I heard earlier
> that Peter Bengtsson was working on something like this as well; perhaps you
> could contact him and ask him what the status is? (but don't wait forever
> for him; just go ahead and do it)
>
> Danny Navarro wrote:
>>
>> Fernando Correa just explained me what is a grokker and what does Upon
>> your feedback I can start publishing the following questions:
>
> I've put in my versions below.
>
>> - What is a Grok directive?
>> A Grok directive is a snippet of code meant to be interpreted by a
>> grokker. [Link to Grok directives reference grok 0.14dev?]
>
> [I wouldn't use 'snippet of code']
>
> A Grok directive is a class or module-level annotation that looks like this:
>
>  grok.foo('information')
>
> If in a class, it annotates the class with extra information used to
> configure the class. If in a module, it annotates the module with this extra
> information. A module-level directive can be used as the default for all
> classes, if it can also occur in a class itself.
>
> Directives are often optional; if they are left out the default value for
> that directive kicks in. The ``grok.require`` directive for example has as
> its default ``zope.Public``, meaning views are public by default.
>
> Grok directives are interpreted by a grokker.
>
>> - What is a grokker?
>> A grokker is a component that extracts grok directives from Python code so
>> that the components are coupled by Zope component machinery (site manager?).
>> You don't need to learn how to write grokkers unless you want to extend Grok
>> itself.
>
> A grokker is a component that configures a class, module or instance with
> Grok. It uses annotations made by directives to determine the details of
> this confirmation. Configuration often entails the registration of a class
> with the Zope Component Architecture (ZCA); an adapter is for instance
> registered with the ZCA by what it adapts and what interface it adapts to.
>
> You don't need to learn how to write grokkers unless you want to extend Grok
> itself with new configuration behavior.
>
>> - What does someone mean when claiming that a component has been grokked?
>> It means that the grokker has acted on the component and has been
>> configured by Zope machinery. It's one of the most frequent words you will
>> read from Grok developers if you follow Grok-dev mailing list.
>
> It means that any relevant grokkers have acted on the component and the
> component has been configured.
>
>> - What are the megrok packages about?
>> The packages that are under megrok namespace package are non-essential
>> Grok packages that extend the basic functionality of Grok. Some of them
>> integrate different Zope 3 packages into an easier to use Grok package which
>> follows Grok conventions for sensible configuration.
>
> [No amendments here. :)]
>
>> - What are the grokcore packages?
>> These are packages that actually make Grok. You don't need to deal with
>> them unless you want to understand how Grok works internally.
>>
>
> These are packages that implement certain features in Grok itself. You don't
> need to deal with them unless you want to understand how Grok works
> internally, or if you want to use bits of Grok outside of Grok itself, for
> instance in a non-Grok Zope 3 application or in a Zope 2 setting.
>
>> Actually I have been compiling a very long list of questions at the same
>> time I was learning Grok and Zope3, but instead of sending them all, I can
>> start publishing FAQs gradually as I learn more about Grok and get feedback
>> from people who can ensure my naive answers are correct.
>
> I think a FAQ is a great initiative! It's definitely another very helpful
> way to help people learn Grok and understand discussions about it.
>
> I think it'd be good if you posted a few more questions & answers you have
> to the mailing list. I'll be happy to write my answers. Even though I did
> write a lot of my own answers here, your answers were very helpful to me in
> writing my own, and it's also interesting to see what other people's answers
> are, so please do continue writing them (unless you really don't know the
> answer of course).
>
> I also invite others to submit answers to the questions you ask here; we can
> combine multiple answers into a good FAQ answer that we can then publish to
> the site.
>
> Regards,
>
> Martijn
>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev@...
> http://mail.zope.org/mailman/listinfo/grok-dev
>

--
Peter Bengtsson,
work www.fry-it.com
home www.peterbe.com
hobby www.issuetrackerproduct.com
_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Martijn Faassen-2]

Peter Bengtsson wrote:
> Danny,
> I actually got started on something but it's too unfinish to be worth
> sending to you.
> What I had in mind was a very simple Grok app which would be like a
> wiki where anybody could add and edit entries and these would then be
> ordered and exported to a .rst file into the svn trunk of Grok itself.
> Perhaps you can do that and I can help if I find the time.

Just as a general note, it's often the case that documentation efforts
by developers change into development efforts by developers to make a
Great Documentation Tool. The drawback of this is that developers much
rather work on Great Tools than on documentation, meaning the
documentation isn't written as the tool isn't quite perfect yet.

That's not a personal criticism, Peter; I know you've been writing
plenty of documentation. It's just one of the things we as a project
should watch out for. So, by all means, Danny, just focus on writing the
FAQ text and we'll worry about a documentation tool for it later.

Regards,

Martijn

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Alexander Limi]

On Thu, 07 Aug 2008 09:31:52 -0700, Martijn Faassen  
<faassen@...> wrote:

> Just as a general note, it's often the case that documentation efforts  
> by developers change into development efforts by developers to make a  
> Great Documentation Tool. The drawback of this is that developers much  
> rather work on Great Tools than on documentation, meaning the  
> documentation isn't written as the tool isn't quite perfect yet.
>
> That's not a personal criticism, Peter; I know you've been writing  
> plenty of documentation. It's just one of the things we as a project  
> should watch out for. So, by all means, Danny, just focus on writing the  
> FAQ text and we'll worry about a documentation tool for it later.

You're still using PloneHelpCenter for the Grok site, right? It has  
functionality for FAQs and a Glossary.

--
Alexander Limi · http://limi.net

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Danny Navarro-2]

Hi,

I have put the questions here:

http://grok.zope.org/documentation/faq

Some of the questions might be better in a Glossary section but for  
now I prefer to put all as FAQ. Later, if there are many questions we  
can extract some of them and report them as glossary terms.

There is no link to the faq section from http://grok.zope.org/documentation 
. I would like to put it under Grok Documentation section in that page  
but not sure how to do that.

I'll send another set of questions about ZODB. I think ZODB is one of  
the strongest advantages about Grok but there are too many  
misconceptions that can be cleared up with some FAQs.

Regards,

Danny

On 7 Aug 2008, at 15:47, Martijn Faassen wrote:

> Hi there,
>
> A FAQ section on grok.zope.org would be very good to have! I heard  
> earlier that Peter Bengtsson was working on something like this as  
> well; perhaps you could contact him and ask him what the status is?  
> (but don't wait forever for him; just go ahead and do it)
>
> Danny Navarro wrote:
>> Fernando Correa just explained me what is a grokker and what does  
>> Upon your feedback I can start publishing the following questions:
>
> I've put in my versions below.
>
>> - What is a Grok directive?
>> A Grok directive is a snippet of code meant to be interpreted by a  
>> grokker. [Link to Grok directives reference grok 0.14dev?]
>
> [I wouldn't use 'snippet of code']
>
> A Grok directive is a class or module-level annotation that looks  
> like this:
>
>  grok.foo('information')
>
> If in a class, it annotates the class with extra information used to  
> configure the class. If in a module, it annotates the module with  
> this extra information. A module-level directive can be used as the  
> default for all classes, if it can also occur in a class itself.
>
> Directives are often optional; if they are left out the default  
> value for that directive kicks in. The ``grok.require`` directive  
> for example has as its default ``zope.Public``, meaning views are  
> public by default.
>
> Grok directives are interpreted by a grokker.
>
>> - What is a grokker?
>> A grokker is a component that extracts grok directives from Python  
>> code so that the components are coupled by Zope component machinery  
>> (site manager?). You don't need to learn how to write grokkers  
>> unless you want to extend Grok itself.
>
> A grokker is a component that configures a class, module or instance  
> with Grok. It uses annotations made by directives to determine the  
> details of this confirmation. Configuration often entails the  
> registration of a class with the Zope Component Architecture (ZCA);  
> an adapter is for instance registered with the ZCA by what it adapts  
> and what interface it adapts to.
>
> You don't need to learn how to write grokkers unless you want to  
> extend Grok itself with new configuration behavior.
>
>> - What does someone mean when claiming that a component has been  
>> grokked?
>> It means that the grokker has acted on the component and has been  
>> configured by Zope machinery. It's one of the most frequent words  
>> you will read from Grok developers if you follow Grok-dev mailing  
>> list.
>
> It means that any relevant grokkers have acted on the component and  
> the component has been configured.
>
>> - What are the megrok packages about?
>> The packages that are under megrok namespace package are non-
>> essential Grok packages that extend the basic functionality of  
>> Grok. Some of them integrate different Zope 3 packages into an  
>> easier to use Grok package which follows Grok conventions for  
>> sensible configuration.
>
> [No amendments here. :)]
>
>> - What are the grokcore packages?
>> These are packages that actually make Grok. You don't need to deal  
>> with them unless you want to understand how Grok works internally.
>>
>
> These are packages that implement certain features in Grok itself.  
> You don't need to deal with them unless you want to understand how  
> Grok works internally, or if you want to use bits of Grok outside of  
> Grok itself, for instance in a non-Grok Zope 3 application or in a  
> Zope 2 setting.
>
>> Actually I have been compiling a very long list of questions at the  
>> same time I was learning Grok and Zope3, but instead of sending  
>> them all, I can start publishing FAQs gradually as I learn more  
>> about Grok and get feedback from people who can ensure my naive  
>> answers are correct.
>
> I think a FAQ is a great initiative! It's definitely another very  
> helpful way to help people learn Grok and understand discussions  
> about it.
>
> I think it'd be good if you posted a few more questions & answers  
> you have to the mailing list. I'll be happy to write my answers.  
> Even though I did write a lot of my own answers here, your answers  
> were very helpful to me in writing my own, and it's also interesting  
> to see what other people's answers are, so please do continue  
> writing them (unless you really don't know the answer of course).
>
> I also invite others to submit answers to the questions you ask  
> here; we can combine multiple answers into a good FAQ answer that we  
> can then publish to the site.
>
> Regards,
>
> Martijn
>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev@...
> http://mail.zope.org/mailman/listinfo/grok-dev

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Danny Navarro-2]

Thanks for the advice,

I'm aware of that, that's why I didn't send all my questions :)

For sure there are other questions more important and relevant for  
more users but for now I think it's better to start with something,  
keep adding questions and reorganize them later.

Danny

On 7 Aug 2008, at 16:15, Baiju M wrote:

> ----- "Martijn Faassen" <faassen@...> wrote:
>> Hi there,
>>
>> A FAQ section on grok.zope.org would be very good to have!
>
> An FAQ for Grok would be really great.  But I have one suggestion,
> please read this article and go through some good FAQs:
> http://svnbook.red-bean.com/nightly/en/svn.foreword.html
>
> Regards,
> Baiju M
> _______________________________________________
> Grok-dev mailing list
> Grok-dev@...
> http://mail.zope.org/mailman/listinfo/grok-dev

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Danny Navarro-2]

On 7 Aug 2008, at 18:31, Martijn Faassen wrote:

> Peter Bengtsson wrote:
>> Danny,
>> I actually got started on something but it's too unfinish to be worth
>> sending to you.
>> What I had in mind was a very simple Grok app which would be like a
>> wiki where anybody could add and edit entries and these would then be
>> ordered and exported to a .rst file into the svn trunk of Grok  
>> itself.
>> Perhaps you can do that and I can help if I find the time.
>
> Just as a general note, it's often the case that documentation  
> efforts by developers change into development efforts by developers  
> to make a Great Documentation Tool. The drawback of this is that  
> developers much rather work on Great Tools than on documentation,  
> meaning the documentation isn't written as the tool isn't quite  
> perfect yet.
>
> That's not a personal criticism, Peter; I know you've been writing  
> plenty of documentation. It's just one of the things we as a project  
> should watch out for. So, by all means, Danny, just focus on writing  
> the FAQ text and we'll worry about a documentation tool for it later.

Agree, just let me start with something ;)

>
>
> Regards,
>
> Martijn
>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev@...
> http://mail.zope.org/mailman/listinfo/grok-dev

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev

[Danny Navarro-2]

On 7 Aug 2008, at 22:08, Alexander Limi wrote:

> On Thu, 07 Aug 2008 09:31:52 -0700, Martijn Faassen <faassen@...
> > wrote:
>
>> Just as a general note, it's often the case that documentation  
>> efforts by developers change into development efforts by developers  
>> to make a Great Documentation Tool. The drawback of this is that  
>> developers much rather work on Great Tools than on documentation,  
>> meaning the documentation isn't written as the tool isn't quite  
>> perfect yet.
>>
>> That's not a personal criticism, Peter; I know you've been writing  
>> plenty of documentation. It's just one of the things we as a  
>> project should watch out for. So, by all means, Danny, just focus  
>> on writing the FAQ text and we'll worry about a documentation tool  
>> for it later.
>
> You're still using PloneHelpCenter for the Grok site, right? It has  
> functionality for FAQs and a Glossary.

Sure, it has FAQs and Glossary functionality. I have already used the  
FAQ functionality.

>
>
> --
> Alexander Limi · http://limi.net
>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev@...
> http://mail.zope.org/mailman/listinfo/grok-dev

_______________________________________________
Grok-dev mailing list
Grok-dev@...
http://mail.zope.org/mailman/listinfo/grok-dev