Grails documentation

classic Classic list List threaded Threaded
20 messages Options
Reply | Threaded
Open this post in threaded view
|

Grails documentation

Steven Devijver
Dear all,

Regardless of when Grails 1.0 will be released, and regardless of
which state its documentation will be in ...

... someday we'll have to offer our users more documentation. The
current documentation on the wiki is useful for the people who are
currently using Grails, meaning people that already know Groovy, Java
and much more.

Grails is however targeted at users that do not posses this knowledge.
This means we need to have documentation that explains practically
everything about Grails, from the first steps to the most advanced
features.

The only way we'll get this kind of documentation is when we plan for
it. This means we have to determine who will read the documentation,
what we'll provide, who will write it, how it will be written, by
when, ...

Everybody will be in London next week so I suggest we have a chat
about documentation then. However, I do suggest we form a
documentation group of no more than 2 or 3 people that report to the
community on their activities and progress. Otherwise it's going to be
too hard to manage. Everybody is welcome to contribute of course.

So, any ideas on Grails' future documentation are welcome as off now.
After we gather all your ideas we'll do a big round table, come to a
conclusion and start working.

Thanks

Steven

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Randall R Schulz
On Sunday 14 October 2007 14:26, Steven Devijver wrote:
> Dear all,
>
> ...
>
> Everybody will be in London next week ...

My god, it's going to be crowded there. But for me, the only person who
won't be there, it should be really quite out here. I've always had
fantasies of walking the streets of San Francisco without anyone else
around...


> ...
>
> Steven


RRS

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Graham O'Regan-2
the guys working on lift had a similar discussion recently;

http://groups.google.com/group/liftweb/browse_frm/thread/68f9c92d0b28b28b/3f6b533ea5ec7bf9#3f6b533ea5ec7bf9

i don't think the fruits are available yet, but seeing as quite a few people working on grails are in london...

Randall R Schulz wrote:
On Sunday 14 October 2007 14:26, Steven Devijver wrote:
  
Dear all,

...

Everybody will be in London next week ...
    

My god, it's going to be crowded there. But for me, the only person who 
won't be there, it should be really quite out here. I've always had 
fantasies of walking the streets of San Francisco without anyone else 
around...


  
...

Steven
    


RRS

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email


  
Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

jondo_w
In reply to this post by Steven Devijver
IMHO there's no need to reinvent the wheel. By that I mean, imitate what others have done successfully.

So when you're all together in Blighty, sipping your ales and draughts, get a general consensus (like everybody vote their top 1-3) on which successful projects/products (doesn't need to be open source) you think have the best documentation, and then those 2-3 Grails documentation people should analyse that documentation for a common format, style and structure. No doubt what worked well for those projects will work well for Grails.

But, just MHO. :-)

Steven Devijver wrote
Dear all,

Regardless of when Grails 1.0 will be released, and regardless of
which state its documentation will be in ...

... someday we'll have to offer our users more documentation. The
current documentation on the wiki is useful for the people who are
currently using Grails, meaning people that already know Groovy, Java
and much more.

Grails is however targeted at users that do not posses this knowledge.
This means we need to have documentation that explains practically
everything about Grails, from the first steps to the most advanced
features.

The only way we'll get this kind of documentation is when we plan for
it. This means we have to determine who will read the documentation,
what we'll provide, who will write it, how it will be written, by
when, ...

Everybody will be in London next week so I suggest we have a chat
about documentation then. However, I do suggest we form a
documentation group of no more than 2 or 3 people that report to the
community on their activities and progress. Otherwise it's going to be
too hard to manage. Everybody is welcome to contribute of course.

So, any ideas on Grails' future documentation are welcome as off now.
After we gather all your ideas we'll do a big round table, come to a
conclusion and start working.

Thanks

Steven

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email
Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Steven Devijver
On 10/16/07, Darryl Pentz <[hidden email]> wrote:

>
> IMHO there's no need to reinvent the wheel. By that I mean, imitate what
> others have done successfully.
>
> So when you're all together in Blighty, sipping your ales and draughts, get
> a general consensus (like everybody vote their top 1-3) on which successful
> projects/products (doesn't need to be open source) you think have the best
> documentation, and then those 2-3 Grails documentation people should analyse
> that documentation for a common format, style and structure. No doubt what
> worked well for those projects will work well for Grails.
>
> But, just MHO. :-)
>

Since open-source doesn't have a good track record when it comes to
documentation. The only good example I know about is Spring.

Do you know any others?

>
> Steven Devijver wrote:
> >
> > Dear all,
> >
> > Regardless of when Grails 1.0 will be released, and regardless of
> > which state its documentation will be in ...
> >
> > ... someday we'll have to offer our users more documentation. The
> > current documentation on the wiki is useful for the people who are
> > currently using Grails, meaning people that already know Groovy, Java
> > and much more.
> >
> > Grails is however targeted at users that do not posses this knowledge.
> > This means we need to have documentation that explains practically
> > everything about Grails, from the first steps to the most advanced
> > features.
> >
> > The only way we'll get this kind of documentation is when we plan for
> > it. This means we have to determine who will read the documentation,
> > what we'll provide, who will write it, how it will be written, by
> > when, ...
> >
> > Everybody will be in London next week so I suggest we have a chat
> > about documentation then. However, I do suggest we form a
> > documentation group of no more than 2 or 3 people that report to the
> > community on their activities and progress. Otherwise it's going to be
> > too hard to manage. Everybody is welcome to contribute of course.
> >
> > So, any ideas on Grails' future documentation are welcome as off now.
> > After we gather all your ideas we'll do a big round table, come to a
> > conclusion and start working.
> >
> > Thanks
> >
> > Steven
> >
> > ---------------------------------------------------------------------
> > To unsubscribe from this list please visit:
> >
> >     http://xircles.codehaus.org/manage_email
> >
> >
> >
>
> --
> View this message in context: http://www.nabble.com/Grails-documentation-tf4623447.html#a13228622
> Sent from the grails - user mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Graeme-Rocher
On 10/16/07, Steven Devijver <[hidden email]> wrote:

> On 10/16/07, Darryl Pentz <[hidden email]> wrote:
> >
> > IMHO there's no need to reinvent the wheel. By that I mean, imitate what
> > others have done successfully.
> >
> > So when you're all together in Blighty, sipping your ales and draughts, get
> > a general consensus (like everybody vote their top 1-3) on which successful
> > projects/products (doesn't need to be open source) you think have the best
> > documentation, and then those 2-3 Grails documentation people should analyse
> > that documentation for a common format, style and structure. No doubt what
> > worked well for those projects will work well for Grails.
> >
> > But, just MHO. :-)
> >
>
> Since open-source doesn't have a good track record when it comes to
> documentation. The only good example I know about is Spring.

Hibernate's docs are good too

Cheers

>
> Do you know any others?
>
> >
> > Steven Devijver wrote:
> > >
> > > Dear all,
> > >
> > > Regardless of when Grails 1.0 will be released, and regardless of
> > > which state its documentation will be in ...
> > >
> > > ... someday we'll have to offer our users more documentation. The
> > > current documentation on the wiki is useful for the people who are
> > > currently using Grails, meaning people that already know Groovy, Java
> > > and much more.
> > >
> > > Grails is however targeted at users that do not posses this knowledge.
> > > This means we need to have documentation that explains practically
> > > everything about Grails, from the first steps to the most advanced
> > > features.
> > >
> > > The only way we'll get this kind of documentation is when we plan for
> > > it. This means we have to determine who will read the documentation,
> > > what we'll provide, who will write it, how it will be written, by
> > > when, ...
> > >
> > > Everybody will be in London next week so I suggest we have a chat
> > > about documentation then. However, I do suggest we form a
> > > documentation group of no more than 2 or 3 people that report to the
> > > community on their activities and progress. Otherwise it's going to be
> > > too hard to manage. Everybody is welcome to contribute of course.
> > >
> > > So, any ideas on Grails' future documentation are welcome as off now.
> > > After we gather all your ideas we'll do a big round table, come to a
> > > conclusion and start working.
> > >
> > > Thanks
> > >
> > > Steven
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe from this list please visit:
> > >
> > >     http://xircles.codehaus.org/manage_email
> > >
> > >
> > >
> >
> > --
> > View this message in context: http://www.nabble.com/Grails-documentation-tf4623447.html#a13228622
> > Sent from the grails - user mailing list archive at Nabble.com.
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe from this list please visit:
> >
> >     http://xircles.codehaus.org/manage_email
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe from this list please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>


--
Graeme Rocher
Grails Project Lead
http://grails.org

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Steven Devijver
On 10/16/07, Graeme Rocher <[hidden email]> wrote:

> On 10/16/07, Steven Devijver <[hidden email]> wrote:
> > On 10/16/07, Darryl Pentz <[hidden email]> wrote:
> > >
> > > IMHO there's no need to reinvent the wheel. By that I mean, imitate what
> > > others have done successfully.
> > >
> > > So when you're all together in Blighty, sipping your ales and draughts, get
> > > a general consensus (like everybody vote their top 1-3) on which successful
> > > projects/products (doesn't need to be open source) you think have the best
> > > documentation, and then those 2-3 Grails documentation people should analyse
> > > that documentation for a common format, style and structure. No doubt what
> > > worked well for those projects will work well for Grails.
> > >
> > > But, just MHO. :-)
> > >
> >
> > Since open-source doesn't have a good track record when it comes to
> > documentation. The only good example I know about is Spring.
>
> Hibernate's docs are good too
>

Yeah, the JBoss doc in general is pretty decent.

We can learn from other teams but in the end we'll have to do it ourselves.

Steven

> Cheers
>
> >
> > Do you know any others?
> >
> > >
> > > Steven Devijver wrote:
> > > >
> > > > Dear all,
> > > >
> > > > Regardless of when Grails 1.0 will be released, and regardless of
> > > > which state its documentation will be in ...
> > > >
> > > > ... someday we'll have to offer our users more documentation. The
> > > > current documentation on the wiki is useful for the people who are
> > > > currently using Grails, meaning people that already know Groovy, Java
> > > > and much more.
> > > >
> > > > Grails is however targeted at users that do not posses this knowledge.
> > > > This means we need to have documentation that explains practically
> > > > everything about Grails, from the first steps to the most advanced
> > > > features.
> > > >
> > > > The only way we'll get this kind of documentation is when we plan for
> > > > it. This means we have to determine who will read the documentation,
> > > > what we'll provide, who will write it, how it will be written, by
> > > > when, ...
> > > >
> > > > Everybody will be in London next week so I suggest we have a chat
> > > > about documentation then. However, I do suggest we form a
> > > > documentation group of no more than 2 or 3 people that report to the
> > > > community on their activities and progress. Otherwise it's going to be
> > > > too hard to manage. Everybody is welcome to contribute of course.
> > > >
> > > > So, any ideas on Grails' future documentation are welcome as off now.
> > > > After we gather all your ideas we'll do a big round table, come to a
> > > > conclusion and start working.
> > > >
> > > > Thanks
> > > >
> > > > Steven
> > > >
> > > > ---------------------------------------------------------------------
> > > > To unsubscribe from this list please visit:
> > > >
> > > >     http://xircles.codehaus.org/manage_email
> > > >
> > > >
> > > >
> > >
> > > --
> > > View this message in context: http://www.nabble.com/Grails-documentation-tf4623447.html#a13228622
> > > Sent from the grails - user mailing list archive at Nabble.com.
> > >
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe from this list please visit:
> > >
> > >     http://xircles.codehaus.org/manage_email
> > >
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe from this list please visit:
> >
> >     http://xircles.codehaus.org/manage_email
> >
> >
>
>
> --
> Graeme Rocher
> Grails Project Lead
> http://grails.org
>
> ---------------------------------------------------------------------
> To unsubscribe from this list please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

darrendavison
In reply to this post by Graeme-Rocher

On Tue, October 16, 2007 1:03 pm, Graeme Rocher wrote:
> On 10/16/07, Steven Devijver <[hidden email]> wrote:
>> Since open-source doesn't have a good track record when it comes to
>> documentation. The only good example I know about is Spring.
>
> Hibernate's docs are good too

as we're discussing groovy and grails, a couple of direct comparisons with
open source equivalents:

Python: http://docs.python.org/index.html
Ruby: http://www.ruby-lang.org/en/documentation/
PHP: http://docs.php.net/manual/en/

and..

Django: http://www.djangoproject.com/documentation/
Rails: http://api.rubyonrails.org/
Seagull: http://trac.seagullproject.org/wiki


IMO (as always) all of those examples are way better than the current
groovy/grails standard.

I picked seagull from the inexhaustible PHP list of frameworks because it was
a wiki based effort and one which looks well organised and navigable.  The
rails example is API doc, not the main manual, but another example of
information that's much harder to find for groovy/grails but just as vital.

D.
--
Darren Davison
Public Key: 0xE855B3EA



---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Steven Devijver
On 10/16/07, Darren Davison <[hidden email]> wrote:

>
> On Tue, October 16, 2007 1:03 pm, Graeme Rocher wrote:
> > On 10/16/07, Steven Devijver <[hidden email]> wrote:
> >> Since open-source doesn't have a good track record when it comes to
> >> documentation. The only good example I know about is Spring.
> >
> > Hibernate's docs are good too
>
> as we're discussing groovy and grails, a couple of direct comparisons with
> open source equivalents:
>
> Python: http://docs.python.org/index.html
> Ruby: http://www.ruby-lang.org/en/documentation/
> PHP: http://docs.php.net/manual/en/
>
> and..
>
> Django: http://www.djangoproject.com/documentation/
> Rails: http://api.rubyonrails.org/
> Seagull: http://trac.seagullproject.org/wiki
>
>
> IMO (as always) all of those examples are way better than the current
> groovy/grails standard.
>
> I picked seagull from the inexhaustible PHP list of frameworks because it was
> a wiki based effort and one which looks well organised and navigable.  The
> rails example is API doc, not the main manual, but another example of
> information that's much harder to find for groovy/grails but just as vital.
>

Thanks for this list.

First of all, I think the current wiki is a great reference for Grails
although not complete.

Other projects are definitely interesting for comparison. However, if
we want to get anywhere we'll have to advance in baby steps.

I have my own ideas on how to do that. Regardless of how we'll tackle
documentation, we 'll have to share the burden, work together as a
team (share responsibility) and plan our efforts.

Excessive complexity also exists in documentation ;-)

Steven

> D.
> --
> Darren Davison
> Public Key: 0xE855B3EA
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Marc Palmer Local
In reply to this post by Graeme-Rocher

On 16 Oct 2007, at 13:03, Graeme Rocher wrote:

> On 10/16/07, Steven Devijver <[hidden email]> wrote:
>> On 10/16/07, Darryl Pentz <[hidden email]> wrote:
>>>
>>> IMHO there's no need to reinvent the wheel. By that I mean,  
>>> imitate what
>>> others have done successfully.
>>>
>>> So when you're all together in Blighty, sipping your ales and  
>>> draughts, get
>>> a general consensus (like everybody vote their top 1-3) on which  
>>> successful
>>> projects/products (doesn't need to be open source) you think have  
>>> the best
>>> documentation, and then those 2-3 Grails documentation people  
>>> should analyse
>>> that documentation for a common format, style and structure. No  
>>> doubt what
>>> worked well for those projects will work well for Grails.
>>>
>>> But, just MHO. :-)
>>>
>>
>> Since open-source doesn't have a good track record when it comes to
>> documentation. The only good example I know about is Spring.
>
> Hibernate's docs are good too
>

I'd have to say Hibernate's are a bit ropey for me. Not detailed  
enough in some areas when I last used them, and the presentation left  
a bit to be desired, but then I guess the same can be said of spring ;-)



---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Steven Devijver
On 10/16/07, Marc Palmer <[hidden email]> wrote:

>
> On 16 Oct 2007, at 13:03, Graeme Rocher wrote:
>
> > On 10/16/07, Steven Devijver <[hidden email]> wrote:
> >> On 10/16/07, Darryl Pentz <[hidden email]> wrote:
> >>>
> >>> IMHO there's no need to reinvent the wheel. By that I mean,
> >>> imitate what
> >>> others have done successfully.
> >>>
> >>> So when you're all together in Blighty, sipping your ales and
> >>> draughts, get
> >>> a general consensus (like everybody vote their top 1-3) on which
> >>> successful
> >>> projects/products (doesn't need to be open source) you think have
> >>> the best
> >>> documentation, and then those 2-3 Grails documentation people
> >>> should analyse
> >>> that documentation for a common format, style and structure. No
> >>> doubt what
> >>> worked well for those projects will work well for Grails.
> >>>
> >>> But, just MHO. :-)
> >>>
> >>
> >> Since open-source doesn't have a good track record when it comes to
> >> documentation. The only good example I know about is Spring.
> >
> > Hibernate's docs are good too
> >
>
> I'd have to say Hibernate's are a bit ropey for me. Not detailed
> enough in some areas when I last used them, and the presentation left
> a bit to be desired, but then I guess the same can be said of spring ;-)
>

Spring had great documentation in 2004/2005. Their documentation has
evolved but it's creation and maintenance has not been very well
planned, it's more a community effort.

For example: some configuration examples, if copied as is, can cause
serious trouble. I've witnessed one application go down on its knees
because of bean definitions that were copied directly from the spring
user doc. I've discovered exactly the same bean definitions in another
application as well.

A user guide should be build with objectives in mind. Writing any user
guide requires an enormous effort. Any planning and goal-setting that
goes into writing it can only make it better.

Some resources:

http://www.williamrice.com/techcomm/writing_user_manuals.html
http://www.slideshare.net/lars3loff/open-source-for-technical-writing-teams/

Steven

>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Steven Devijver
Here's an example of what I think the Grails user guide should look
like (see attachment).

Steven

On 10/16/07, Steven Devijver <[hidden email]> wrote:

> On 10/16/07, Marc Palmer <[hidden email]> wrote:
> >
> > On 16 Oct 2007, at 13:03, Graeme Rocher wrote:
> >
> > > On 10/16/07, Steven Devijver <[hidden email]> wrote:
> > >> On 10/16/07, Darryl Pentz <[hidden email]> wrote:
> > >>>
> > >>> IMHO there's no need to reinvent the wheel. By that I mean,
> > >>> imitate what
> > >>> others have done successfully.
> > >>>
> > >>> So when you're all together in Blighty, sipping your ales and
> > >>> draughts, get
> > >>> a general consensus (like everybody vote their top 1-3) on which
> > >>> successful
> > >>> projects/products (doesn't need to be open source) you think have
> > >>> the best
> > >>> documentation, and then those 2-3 Grails documentation people
> > >>> should analyse
> > >>> that documentation for a common format, style and structure. No
> > >>> doubt what
> > >>> worked well for those projects will work well for Grails.
> > >>>
> > >>> But, just MHO. :-)
> > >>>
> > >>
> > >> Since open-source doesn't have a good track record when it comes to
> > >> documentation. The only good example I know about is Spring.
> > >
> > > Hibernate's docs are good too
> > >
> >
> > I'd have to say Hibernate's are a bit ropey for me. Not detailed
> > enough in some areas when I last used them, and the presentation left
> > a bit to be desired, but then I guess the same can be said of spring ;-)
> >
>
> Spring had great documentation in 2004/2005. Their documentation has
> evolved but it's creation and maintenance has not been very well
> planned, it's more a community effort.
>
> For example: some configuration examples, if copied as is, can cause
> serious trouble. I've witnessed one application go down on its knees
> because of bean definitions that were copied directly from the spring
> user doc. I've discovered exactly the same bean definitions in another
> application as well.
>
> A user guide should be build with objectives in mind. Writing any user
> guide requires an enormous effort. Any planning and goal-setting that
> goes into writing it can only make it better.
>
> Some resources:
>
> http://www.williamrice.com/techcomm/writing_user_manuals.html
> http://www.slideshare.net/lars3loff/open-source-for-technical-writing-teams/
>
> Steven
>
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe from this list please visit:
> >
> >     http://xircles.codehaus.org/manage_email
> >
> >
>

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

sample-grails-user-guide.zip (5K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

RE: Grails documentation

Karsten Silz-2
In reply to this post by Steven Devijver
> -----Original Message-----
> From: Steven Devijver [mailto:[hidden email]]
> Sent: Tuesday, October 16, 2007 8:39
> To: [hidden email]
> Subject: Re: [grails-user] Grails documentation

[...]

> Thanks for this list.
>
> First of all, I think the current wiki is a great reference
> for Grails although not complete.
>
> Other projects are definitely interesting for comparison.
> However, if we want to get anywhere we'll have to advance in
> baby steps.
>
> I have my own ideas on how to do that. Regardless of how
> we'll tackle documentation, we 'll have to share the burden,
> work together as a team (share responsibility) and plan our efforts.
>
> Excessive complexity also exists in documentation ;-)

Hi!

I'm a Grails newbie as well, so I feel the documentation pain.  :-)

The first thing the Grails project has to decide is who is the target group
of Grails.  If that is "hard-core developers" only then you're already set
with the documentation - because these guys google for stack traces, dig
through the mailing lists and love to read your source code; they probably
even see a lack of source code as a challenge to figure stuff out
themselves.

If Grails targets more mainstream developers then you guys have some
documentation work ahead.  A mainstream developer comes to Grails because it
promises to save time and effort.  I'm sure Grails does but if a problem in
the Grails app can't be solved because it's not documented or the
documentation is out of date, then this promise is in vain, and the
developer will turn elsewhere.

What I suggest is "goal-oriented documentation" in addition to the (more
reference-like) documentation already out there on the Grails page / the
Wiki - thinking from a Grails user perspective, so to speak.  What does that
mean?  With Grails, users have different main goals: You write an
application from scratch with no existing data (the sweet spot of Grails, I
think), you write an application from scratch with some / all legacy data,
you want to add to Grails to an existing Java app (does that make sense?),
and so forth.  You should structure the documentation according to these
main goals, and this would lead you to a base Grails application.  Beyond
these main goals, you have sub-goals that are shared among the different
main goals - structuring the home page, adding users / authentication /
authorization (again, either from scratch or by integrating existing
infrastructure), adding Ajax features, adding full-text / record-based
search, using some advanced UI features (rich-text editor, using tabs,
uploading and displaying images / PDFs / files etc.), versioning of records
etc.  They should be documented as self-contained units as well.

The benefit of this goal-oriented documentation would be that a developer
can pick and choose his "path" (like picking from a menu in the restaurant
:-), starting with the main goal and then picking sub-goals, and get the
proper documentation for at least the majority of development activities.
As for the physical shape of the documentation, I would suggest either an
HTML ZIP or a PDF with working samples alongside.  And maintaining /
extending that documentation and the samples for each release is mandatory;
if either the documentation or the samples don't work / are incomplete, then
in my mind this is a showstopper bug holding up the release ("If it isn't
documented then it doesn't exist!").

---
Karsten Silz

 
> Steven
>
> > D.
> > --
> > Darren Davison
> > Public Key: 0xE855B3EA


---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Steven Devijver
On 10/16/07, Karsten Silz <[hidden email]> wrote:

> > -----Original Message-----
> > From: Steven Devijver [mailto:[hidden email]]
> > Sent: Tuesday, October 16, 2007 8:39
> > To: [hidden email]
> > Subject: Re: [grails-user] Grails documentation
>
> [...]
>
> > Thanks for this list.
> >
> > First of all, I think the current wiki is a great reference
> > for Grails although not complete.
> >
> > Other projects are definitely interesting for comparison.
> > However, if we want to get anywhere we'll have to advance in
> > baby steps.
> >
> > I have my own ideas on how to do that. Regardless of how
> > we'll tackle documentation, we 'll have to share the burden,
> > work together as a team (share responsibility) and plan our efforts.
> >
> > Excessive complexity also exists in documentation ;-)
>
> Hi!
>
> I'm a Grails newbie as well, so I feel the documentation pain.  :-)
>
> The first thing the Grails project has to decide is who is the target group
> of Grails.  If that is "hard-core developers" only then you're already set
> with the documentation - because these guys google for stack traces, dig
> through the mailing lists and love to read your source code; they probably
> even see a lack of source code as a challenge to figure stuff out
> themselves.
>
> If Grails targets more mainstream developers then you guys have some
> documentation work ahead.  A mainstream developer comes to Grails because it
> promises to save time and effort.  I'm sure Grails does but if a problem in
> the Grails app can't be solved because it's not documented or the
> documentation is out of date, then this promise is in vain, and the
> developer will turn elsewhere.
>
> What I suggest is "goal-oriented documentation" in addition to the (more
> reference-like) documentation already out there on the Grails page / the
> Wiki - thinking from a Grails user perspective, so to speak.  What does that
> mean?  With Grails, users have different main goals: You write an
> application from scratch with no existing data (the sweet spot of Grails, I
> think), you write an application from scratch with some / all legacy data,
> you want to add to Grails to an existing Java app (does that make sense?),
> and so forth.  You should structure the documentation according to these
> main goals, and this would lead you to a base Grails application.  Beyond
> these main goals, you have sub-goals that are shared among the different
> main goals - structuring the home page, adding users / authentication /
> authorization (again, either from scratch or by integrating existing
> infrastructure), adding Ajax features, adding full-text / record-based
> search, using some advanced UI features (rich-text editor, using tabs,
> uploading and displaying images / PDFs / files etc.), versioning of records
> etc.  They should be documented as self-contained units as well.
>
> The benefit of this goal-oriented documentation would be that a developer
> can pick and choose his "path" (like picking from a menu in the restaurant
> :-), starting with the main goal and then picking sub-goals, and get the
> proper documentation for at least the majority of development activities.
> As for the physical shape of the documentation, I would suggest either an
> HTML ZIP or a PDF with working samples alongside.  And maintaining /
> extending that documentation and the samples for each release is mandatory;
> if either the documentation or the samples don't work / are incomplete, then
> in my mind this is a showstopper bug holding up the release ("If it isn't
> documented then it doesn't exist!").
>

Amen :-)

> ---
> Karsten Silz
>
>
> > Steven
> >
> > > D.
> > > --
> > > Darren Davison
> > > Public Key: 0xE855B3EA
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list please visit:
>
>     http://xircles.codehaus.org/manage_email
>
>

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

jondo_w
Just to throw one more into the hat. A while back I used Derby (then still called Cloudscape) as an embedded client database and I was impressed with how IBM had structured the documentation. There were separate guides (in this case, PDF's) depending on what you were doing. So there were the following:

    * Getting Started with IBM Cloudscape
    * IBM Cloudscape Developer's Guide
    * IBM Cloudscape Server and Administration Guide
    * IBM Cloudscape Reference Manual
    * IBM Cloudscape Tools and Utilities Guide
    * Tuning IBM Cloudscape Guide

So for just starting off with Cloudscape, you could go through the 'Getting Started' guide. The developers guide was for the advanced user, and then the reference guide was exactly that - there for reference. The thing you checked back with if you weren't sure of syntax or the inner workings of some feature.

Regardless, one of the most useful aspects of all of the guides is that they were very well indexed. So if I knew what I was looking for, but wasn't sure where to look, my one stop shop was the index at the end of the PDF. The index notes were clickable for added convenience.

- Darryl
Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Mark Rambow-2
Hi Steven

your afford to get a better documentation is highly appreciated,
there are a lot of black holes in the current online doc, but its
improving since 0.5 I think.

What I would like to see is a http://www.therailsway.com similar approach,
its community based, can be in blog/wiki style and gives best practices
to learn from.
So maybe something similar could be integrated in an online documentation.

And as some others said in this thread problem => solution approach
would help many developers,
who want to try Grails and have experience with other webframeworks.
A good entry point to that would be an extended FAQ. The mailing list
often have a lot of similar questions, which could be avoided....

just my two cents

Mark

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

JamesPage
Would it not be a great idea to use Hamish's wiki software, as then we would be 'eating our own dogfood'?

If Hamish was up for the idea could anybody host it?

James

On 10/22/07, Mark Rambow <[hidden email]> wrote:
Hi Steven

your afford to get a better documentation is highly appreciated,
there are a lot of black holes in the current online doc, but its
improving since 0.5 I think.

What I would like to see is a http://www.therailsway.com similar approach,
its community based, can be in blog/wiki style and gives best practices
to learn from.
So maybe something similar could be integrated in an online documentation.

And as some others said in this thread problem => solution approach
would help many developers,
who want to try Grails and have experience with other webframeworks.
A good entry point to that would be an extended FAQ. The mailing list
often have a lot of similar questions, which could be avoided....

just my two cents

Mark

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

hamishagain@dcs.shef.ac.uk
nice idea, but I don't think it has enough functionality yet :-(

also the codehaus infrastructure is already in place and the community knows
how to use it

h


James Page wrote:

> Would it not be a great idea to use Hamish's wiki software, as then we
> would be 'eating our own dogfood'?
>
> If Hamish was up for the idea could anybody host it?
>
> James
>
> On 10/22/07, *Mark Rambow* <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     Hi Steven
>
>     your afford to get a better documentation is highly appreciated,
>     there are a lot of black holes in the current online doc, but its
>     improving since 0.5 I think.
>
>     What I would like to see is a http://www.therailsway.com similar
>     approach,
>     its community based, can be in blog/wiki style and gives best practices
>     to learn from.
>     So maybe something similar could be integrated in an online
>     documentation.
>
>     And as some others said in this thread problem => solution approach
>     would help many developers,
>     who want to try Grails and have experience with other webframeworks.
>     A good entry point to that would be an extended FAQ. The mailing list
>     often have a lot of similar questions, which could be avoided....
>
>     just my two cents
>
>     Mark
>
>     ---------------------------------------------------------------------
>     To unsubscribe from this list please visit:
>
>         http://xircles.codehaus.org/manage_email
>
>

--
Hamish
http://www.dcs.shef.ac.uk/~hamish/

---------------------------------------------------------------------
To unsubscribe from this list please visit:

    http://xircles.codehaus.org/manage_email

Reply | Threaded
Open this post in threaded view
|

Re: Grails documentation

Daniel Kimmig
In reply to this post by Steven Devijver
One major pain point of the current documentation is the lack of a navigation-trail. If I have made my way into the depth of the docs (e.g. Docs for "Config.groovy"), it is very hard to go back or lets say go to the upper category (e.g. "Configuration").

Very often it is faster for me to hit the Google Search Box in my browser with the docs search term that I would like to see, then acutally navigating in the user guide. I think if we could build a wiki-like infrastructure for te community to fill with best-practices/guides and hook that up with a great way of navigating, I think that would be a good solution.

Although my experiences with Grails are very young, I would love to contribute to the documentation. I just dont know a place where I could start / where my infos would be of any value. Often I find very interesting solutions in the mailing lists that are not explained in the user guide. Maybe thats a starting point.


Oh, and make the slides of Grails Exchange freely available for download. Thats some documentation, too.
Reply | Threaded
Open this post in threaded view
|

RE: Grails documentation

Max David Krüper
I'd like to contribute to the documentation, but as well I do not know where to start. maybe it should be branched into different versions. now it's all mixed.

I like the symfony documentation.. click on "Official documentation"

http://www.symfony-project.com/doc/1_0/


> Date: Mon, 22 Oct 2007 09:05:40 -0700
> From: [hidden email]
> To: [hidden email]
> Subject: Re: [grails-user] Grails documentation
>
>
> One major pain point of the current documentation is the lack of a
> navigation-trail. If I have made my way into the depth of the docs (e.g.
> Docs for "Config.groovy"), it is very hard to go back or lets say go to the
> upper category (e.g. "Configuration").
>
> Very often it is faster for me to hit the Google Search Box in my browser
> with the docs search term that I would like to see, then acutally navigating
> in the user guide. I think if we could build a wiki-like infrastructure for
> te community to fill with best-practices/guides and hook that up with a
> great way of navigating, I think that would be a good solution.
>
> Although my experiences with Grails are very young, I would love to
> contribute to the documentation. I just dont know a place where I could
> start / where my infos would be of any value. Often I find very interesting
> solutions in the mailing lists that are not explained in the user guide.
> Maybe thats a starting point.
>
>
> Oh, and make the slides of Grails Exchange freely available for download.
> Thats some documentation, too.
> --
> View this message in context: http://www.nabble.com/Grails-documentation-tf4623447.html#a13344511
> Sent from the grails - user mailing list archive at Nabble.com.
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list please visit:
>
> http://xircles.codehaus.org/manage_email
>


Schon gesehen? Tolle Bilder von Sarah Connor gibt es hier! Live Search