Grails HOWTOs

[pledbrook]

Hi,

Rodrigo brought up Rails guides in his "why I prefer Rails" blog post
and I've heard others in the past point at them and say we should have
something similar. So it got me to thinking about it and I'm now
wondering whether we should have a simple GitHub project for Grails
howtos. Here's my reasoning:

1. The user and reference guides are really a reference. They're not
task oriented, like a howto would be.

2. The wiki could be used for howtos, but it has weaknesses:

  - Editing isn't as convenient as using your own text editor with local files
  - Versioning isn't as powerful as git
  - Weaker editorial control
  - Harder to support multiple languages

Is it worthwhile looking into devising another infrastructure for
creating, editing and publishing howtos, a la Rails Guides?

Thanks,

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

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

    http://xircles.codehaus.org/manage_email

[Daniel Henrique Alves Lima]

    Hi.

    If my opinion matter for anything, I like the idea of having HOWTOs
and of using a proper infrastructure to make them. Maybe I'm misusing
the Grails wiki infra, but I have lost my changes a few times, when
writing or reviewing a big document (caused by session expiration and
etc) and I haven't seen an option for saving a draft or something like that.

    Thanks.

       Best regards,

             Daniel.

Peter Ledbrook wrote:

> Hi,
>
> Rodrigo brought up Rails guides in his "why I prefer Rails" blog post
> and I've heard others in the past point at them and say we should have
> something similar. So it got me to thinking about it and I'm now
> wondering whether we should have a simple GitHub project for Grails
> howtos. Here's my reasoning:
>
> 1. The user and reference guides are really a reference. They're not
> task oriented, like a howto would be.
>
> 2. The wiki could be used for howtos, but it has weaknesses:
>
>   - Editing isn't as convenient as using your own text editor with local files
>   - Versioning isn't as powerful as git
>   - Weaker editorial control
>   - Harder to support multiple languages
>
> Is it worthwhile looking into devising another infrastructure for
> creating, editing and publishing howtos, a la Rails Guides?
>
> Thanks,
>
> Peter
>
>  

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

    http://xircles.codehaus.org/manage_email

[Nick Vaidyanathan]

So the gist is essentially Grails should aggregate the content in http://www.grails.org/Tutorials, http://grails.org/Grails+Screencasts, http://www.grails.org/FAQ, and much of the content included in the books at http://grails.org/Books into a taxonomized and cohesive "one stop shop" walk-through from soup-to-nuts of the framework that's hosted on a shared source code repository? 

Seems worthy.

Seems like it should be a team effort, and is a massive one. I'm not sure that the problem is a lack of availability of most of this information. Tons has been written on Grails and more is written every day as it seems to be rising in popularity in the Java world (for good reason), and now to the wider web world as a whole (which breeds special problems). 

It seems like a way to taxonomize, rate, and bring up-to-date [much like is being done in the plugin portal] the disparate information already written, remove all those other pages (one problem I consistently find on the grails site is too much [this old information has moved here]. It'd be nice to just kill those pages and insert 302s) and agglomerate it into one place would be more convenient and useful than trying to regenerate a lot of that writing again from scratch. 

Seems like a shared github would be cool. 

The Rails Guides are way prettier than the Grails site right now. While the aesthetic will probably change in Grails 2.0 (it seems to have in the reference documentation, which is a lot nicer), bringing the rest of the site to that state would help.

 

I like the Django Book's commenting piece on different parts of the guide, and the Java Tutorials "Trails" are an excellent organizational scheme. 

On Sat, Aug 13, 2011 at 4:16 AM, Daniel Henrique Alves Lima <[hidden email]> wrote:

  Hi.

  If my opinion matter for anything, I like the idea of having HOWTOs and of using a proper infrastructure to make them. Maybe I'm misusing the Grails wiki infra, but I have lost my changes a few times, when writing or reviewing a big document (caused by session expiration and etc) and I haven't seen an option for saving a draft or something like that.

  Thanks.

     Best regards,

           Daniel.

Peter Ledbrook wrote:

Hi,

Rodrigo brought up Rails guides in his "why I prefer Rails" blog post
and I've heard others in the past point at them and say we should have
something similar. So it got me to thinking about it and I'm now
wondering whether we should have a simple GitHub project for Grails
howtos. Here's my reasoning:

1. The user and reference guides are really a reference. They're not
task oriented, like a howto would be.

2. The wiki could be used for howtos, but it has weaknesses:

 - Editing isn't as convenient as using your own text editor with local files
 - Versioning isn't as powerful as git
 - Weaker editorial control
 - Harder to support multiple languages

Is it worthwhile looking into devising another infrastructure for
creating, editing and publishing howtos, a la Rails Guides?

Thanks,

Peter

 

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

  http://xircles.codehaus.org/manage_email

[Giancarlo Angulo]

I agree with the shared git project.
================================
                   Giancarlo Angulo
================================
-----|-^_^X@^_^,=====|+^_^X~_~@-----

On Sat, Aug 13, 2011 at 6:29 PM, Peter Ledbrook <[hidden email]> wrote:

Hi,

Rodrigo brought up Rails guides in his "why I prefer Rails" blog post
and I've heard others in the past point at them and say we should have
something similar. So it got me to thinking about it and I'm now
wondering whether we should have a simple GitHub project for Grails
howtos. Here's my reasoning:

1. The user and reference guides are really a reference. They're not
task oriented, like a howto would be.

2. The wiki could be used for howtos, but it has weaknesses:

 - Editing isn't as convenient as using your own text editor with local files
 - Versioning isn't as powerful as git
 - Weaker editorial control
 - Harder to support multiple languages

Is it worthwhile looking into devising another infrastructure for
creating, editing and publishing howtos, a la Rails Guides?

Thanks,

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

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

   http://xircles.codehaus.org/manage_email

[mr.dustmite]

I fully support this effort. I find myself answering a lot of the same HOW-TO question on the freenode IRC #grails channel, and being able to point someone to an "official HOW-TO" would be really nice.

I'm willing to donate what time I can to adding content once this is ready for authors too.

[pledbrook]

> So the gist is essentially Grails should aggregate the content
> in http://www.grails.org/Tutorials, http://grails.org/Grails+Screencasts, http://www.grails.org/FAQ, and
> much of the content included in the books at http://grails.org/Books into a
> taxonomized and cohesive "one stop shop" walk-through from soup-to-nuts of
> the framework that's hosted on a shared source code repository?

Not really. Screencasts will remain screencasts and the tutorials will
almost certainly stay but with a different approach. It won't stay a
wiki page. Also, I don't think we're allowed to just lift stuff from
the items mention on Books ;)

That said, some of the tutorials will hopefully become guides/howtos.
And yes, the source for these will be on a shared source repository
(GitHub).

> Seems worthy.
> Seems like it should be a team effort, and is a massive one. I'm not sure
> that the problem is a lack of availability of most of this information. Tons
> has been written on Grails and more is written every day as it seems to be
> rising in popularity in the Java world (for good reason), and now to the
> wider web world as a whole (which breeds special problems).
> It seems like a way to taxonomize, rate, and bring up-to-date [much like is
> being done in the plugin portal] the disparate information already written,
> remove all those other pages (one problem I consistently find on the grails
> site is too much [this old information has moved here]. It'd be nice to just
> kill those pages and insert 302s) and agglomerate it into one place would be
> more convenient and useful than trying to regenerate a lot of that writing
> again from scratch.

So, a few points:

1. I've finally implemented permanent redirect for deprecated wiki
pages that have a alternative URI
2. I now have a page displaying all wiki pages from which I can prune
the ones that are just tests
3. I would like to get something similar to the plugin portal for
other parts of the site, including screencasts and tutorials

A lot of existing value is in blog posts, so hopefully having a common
repository for howtos will encourage the blog authors to migrate their
content over.

> I like the Django Book's commenting piece on different parts of the
> guide, and the Java Tutorials "Trails" are an excellent organizational
> scheme.

Commenting could be tricky to implement, or certainly to implement
well. Not really a priority at this point I'm afraid, although
definitely worth keeping in mind.

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

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

    http://xircles.codehaus.org/manage_email