[ANN] Documentation effort and site redesign

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
51 messages Options
123456
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
Hi Andrey,

DocBook is an option.

A great advantage of DocBook, I think, is how it's already ready for producing single-page and multi-page HTML documentation, as well as PDF outputs -- although I haven't looked at how friendly / customizable this is.

The drawback though might be more around the fact it's a bit painful to work with XML these days, and apart from the Xmlmind tool (if I recall the name correctly), the tooling isn't too friendly for authoring content.

With doc in Markdown format, they'd appear nicely on Github. And it'd be easy for people to edit / fork live on Github to fix obvious typos or contribute changes (and visualize them easily on spot without requiring actually "building" the output)
Many tools know how to grok that syntax nowadays (from Vim to IDEs, as well as dedicated tools like Mou on macs).
There's a great Java library for Markdown which also understands several extensions to the basic Markdown syntax (the Pegdown library on Github).
With the parser, I can easily retrieve the code snippets so as to turn them into executable tests (I could certainly do that with Docbook's XML as well, if I can extend it with my own attributes or piggyback on existing ones).

With Markdown however, there's just the HTML output, and nothing out-of-the-box for different formats (multi vs single page), or for PDF output.

Guillaume


On Fri, Feb 8, 2013 at 7:17 PM, Andrey Bloschetsov <[hidden email]> wrote:
The Springsource documentation is very usable and clear. For creating
they using DocBook format it is a special format for technical
documentation (http://en.wikipedia.org/wiki/DocBook).

Spring Framework documentation source:
https://github.com/SpringSource/spring-framework/tree/3.2.x/src/reference/docbook

Spring Framework documentation in HTML:
http://static.springsource.org/spring/docs/3.2.x/spring-framework-reference/html/

2013/2/8 Guillaume Laforge <[hidden email]>:
> Thanks!
>
>
> On Fri, Feb 8, 2013 at 3:31 PM, Morten Hindsholm <[hidden email]>
> wrote:
>>
>> JIRA created: http://jira.codehaus.org/browse/GROOVY-5983
>>
>> /\/\orten
>>
>>
>> On Fri, Feb 8, 2013 at 3:20 PM, Guillaume Laforge <[hidden email]>
>> wrote:
>>>
>>> Hi Morten,
>>>
>>> On Fri, Feb 8, 2013 at 3:10 PM, Morten Hindsholm <[hidden email]>
>>> wrote:
>>>>
>>>> Improving the documentation is indeed a good idea. I tend to use Google
>>>> as the main entry point for looking up Groovy details, but a well-structured
>>>> documentation site would definitely be better.
>>>>
>>>> Regarding styling etc I like the Grails documentation and I think it
>>>> might be used as inspiration.
>>>>
>>>> And the number one issue I am having with the current GroovyDoc: The
>>>> 'package' link on pages like this
>>>> http://groovy.codehaus.org/groovy-jdk/java/util/Collection.html is not
>>>> enabled. That means that you cannot easily navigate from Collection to List
>>>> to ... I would love to see that fixed!
>>>
>>>
>>> Could you please file a JIRA issue for that one?
>>>
>>>>
>>>> But of course: the fact that the documentation is inadequate doesn't
>>>> mean that Groovy is!
>>>
>>>
>>> Hehe, sure!
>>> Thanks for saying it :-)
>>>
>>> Guillaume
>>>
>>>>
>>>> /\/\orten
>>>>
>>>>
>>>> On Fri, Feb 8, 2013 at 2:31 PM, Guillaume Laforge <[hidden email]>
>>>> wrote:
>>>>>
>>>>> Hi all,
>>>>>
>>>>> Groovy is a very mature and widely used language on the Java platform,
>>>>> with hundred thousands of developers worldwide.
>>>>> It's stable and fast, flexible and readable, has got plenty of
>>>>> interesting use cases (DSLs, testing...), is feature-packed, and it's got a
>>>>> very rich ecosystem of successful projects (Grails, Gradle, Griffon, Spock,
>>>>> Geb, Gaelyk, to name but a few)
>>>>>
>>>>> However, one area where the Groovy project can do better is with its
>>>>> documentation.
>>>>>
>>>>> For instance, if you read the recent DrDobbs editorial, there were some
>>>>> valid points made on this topic. And it's true that our documentation can be
>>>>> greatly improved.
>>>>>
>>>>> Despite its 1000+ pages of wiki content, it's hard to find the
>>>>> information you're looking for, it's of very uneven quality and style, lots
>>>>> of pages are outdated or show samples with mistakes in them, and there are
>>>>> also holes for features not covered or not explained in details.
>>>>>
>>>>> We're launching an effort towards overhauling our documentation and web
>>>>> presence.
>>>>>
>>>>> And I'd love if you could take part in that effort, even if only by
>>>>> telling us about your expectations regarding the website, the documentation,
>>>>> etc., or even by helping us authoring content, of course.
>>>>>
>>>>>
>>>>> For the website, we'll need a fresh new skin, modern and sexy, that
>>>>> makes visitors want to learn more about Groovy and try it.
>>>>> We should be able to easily add sections as we progress along its
>>>>> rework, so as to be able to later publish case studies, testimonials,
>>>>> interactive tutorials, screencasts, news, events, jobs, etc.
>>>>> We're interested in what you would like to see on the front page when
>>>>> you land on the Groovy website, how you would like the site to be organized,
>>>>> etc.
>>>>>
>>>>> If you have ideas of sites whose design inspire you, please don't
>>>>> hesitate to share them.
>>>>> Also don't hesitate to tell us what kind of sections or content you'd
>>>>> like to see showcased on the site.
>>>>>
>>>>>
>>>>> For the documentation, we need to start anew, even if there's
>>>>> definitely content and examples we can take inspiration from from our
>>>>> current wiki.
>>>>>
>>>>> The documentation should be versioned, so that we don't have to ask
>>>>> ourselves from which version this or that feature is available. It also
>>>>> means we should be able to host it alongside our source code, so as to tie
>>>>> the documentation with its code version and be bundled easily when we do our
>>>>> releases.
>>>>> Visitors will be able to navigate to the "latest" version or to some
>>>>> older versions (usually the latest update of a given branch, like 1.8.9,
>>>>> 2.0.6, 2.1.0, etc...)
>>>>>
>>>>> It should also be possible to download it from the website, in HTML at
>>>>> least, but ideally also in PDF form.
>>>>> If you have some best practices for PDF conversion, we're also happy to
>>>>> hear your thoughts.
>>>>>
>>>>> The original format of documentation will likely be in Markdown, as
>>>>> it's a format which is well supported by text editors, IDEs and tools.
>>>>> A nice benefit too, is it's automatically rendered on Github where the
>>>>> Groovy sources are hosted, which also means that it should be easy for
>>>>> contributors to fork and edit the documentation on spot, through the Github
>>>>> interface.
>>>>>
>>>>> The documentation should also be executable, in the sense that we can
>>>>> run the examples as unit tests, as part of our build, so as to ensure that
>>>>> the embedded samples are always in sync with our codebase, thus ensuring
>>>>> that the documentation is properly up-to-date.
>>>>> For that purpose, I've been toying on-and-off on an executable
>>>>> documentation tool, that consumes some wiki markup (not yet Markdown but
>>>>> I'll migrate), that extracts the code samples and run them as unit tests.
>>>>> I'm intending to use that tool for our executable documentation.
>>>>> It's not yet ready, but for those interested in contributing, I'm happy
>>>>> to discuss how we can evolve it for our use.
>>>>>
>>>>>
>>>>> Documenting the language and its libraries with nice narrative and
>>>>> examples is one thing, but there's also the JavaDoc / GroovyDoc
>>>>> documentation!
>>>>> Our GroovyDoc, in particular, looks like the old JavaDoc format, not
>>>>> very sexy or appealing.
>>>>> It'd be nice if the look'n feel of the GroovyDoc was sexier and that it
>>>>> looked coherent with the website redesign, sharing the same style.
>>>>>
>>>>> Also, we should make it a little bit more dynamic (the ScalaDoc is a
>>>>> great example of that), so that it's possible to search classes or methods
>>>>> through JavaScript.
>>>>> It's also an area where you can participate, in particular if you've
>>>>> got some JavaScript ninja skills, it might be a nice contribution too.
>>>>>
>>>>> One last aspect to consider also here, is with the Groovy JDK methods
>>>>> (or also with your own extension modules).
>>>>> We're wondering how to somehow decorate an existing API or the JDK
>>>>> itself with methods added by Groovy or your own modules.
>>>>> How to best represent that in the context of your JavaDoc/GroovyDoc, or
>>>>> layered on top of the JDK documentation (but copyright issues apply...)
>>>>> We'd be happy to hear your thoughts about that.
>>>>>
>>>>>
>>>>> Well, that was a long email, and there are plenty more ideas and open
>>>>> questions that I could share with you on this big and important topic. But I
>>>>> wanted to start a discussion with you all about this initiative, to hear
>>>>> your feedback.
>>>>> Then we'll derive a more actionable list of things to do to achieve the
>>>>> overall goal as we progress along!
>>>>>
>>>>> Thanks a lot for your attention, if you've read through all this, and
>>>>> I'm looking forward to hearing from you!
>>>>>
>>>>>
>>>>> --
>>>>> Guillaume Laforge
>>>>> Groovy Project Manager
>>>>> SpringSource, a division of VMware
>>>>>
>>>>> Blog: http://glaforge.appspot.com/
>>>>> Social: @glaforge / Google+
>>>>
>>>>
>>>
>>>
>>>
>>> --
>>> Guillaume Laforge
>>> Groovy Project Manager
>>> Head of Groovy Development at SpringSource
>>> http://www.springsource.com/g2one
>>
>>
>
>
>
> --
> Guillaume Laforge
> Groovy Project Manager
> Head of Groovy Development at SpringSource
> http://www.springsource.com/g2one



--
Andrey Bloschetsov

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

    http://xircles.codehaus.org/manage_email





--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
In reply to this post by Scott Hickey-2
Right, Gradle went with Docbook, as far as I can see, and I think they added some layer for testing some of the snippets of code that are contained in the documentation.

The "executable" aspect is important in my opinion, to keep the documentation as "alive" as possible, avoiding becoming out-dated quickly.

But well, I'm not too fond of using XML for the documentation :-(


On Fri, Feb 8, 2013 at 7:26 PM, Scott Hickey <[hidden email]> wrote:
iirc, Hans has a nice documentation system as part of Gradle as well.

Scott Hickey

On Fri, Feb 8, 2013 at 12:17 PM, Andrey Bloschetsov
<[hidden email]> wrote:
> The Springsource documentation is very usable and clear. For creating
> they using DocBook format it is a special format for technical
> documentation (http://en.wikipedia.org/wiki/DocBook).
>
> Spring Framework documentation source:
> https://github.com/SpringSource/spring-framework/tree/3.2.x/src/reference/docbook
>
> Spring Framework documentation in HTML:
> http://static.springsource.org/spring/docs/3.2.x/spring-framework-reference/html/
>
> 2013/2/8 Guillaume Laforge <[hidden email]>:
>> Thanks!
>>
>>
>> On Fri, Feb 8, 2013 at 3:31 PM, Morten Hindsholm <[hidden email]>
>> wrote:
>>>
>>> JIRA created: http://jira.codehaus.org/browse/GROOVY-5983
>>>
>>> /\/\orten
>>>
>>>
>>> On Fri, Feb 8, 2013 at 3:20 PM, Guillaume Laforge <[hidden email]>
>>> wrote:
>>>>
>>>> Hi Morten,
>>>>
>>>> On Fri, Feb 8, 2013 at 3:10 PM, Morten Hindsholm <[hidden email]>
>>>> wrote:
>>>>>
>>>>> Improving the documentation is indeed a good idea. I tend to use Google
>>>>> as the main entry point for looking up Groovy details, but a well-structured
>>>>> documentation site would definitely be better.
>>>>>
>>>>> Regarding styling etc I like the Grails documentation and I think it
>>>>> might be used as inspiration.
>>>>>
>>>>> And the number one issue I am having with the current GroovyDoc: The
>>>>> 'package' link on pages like this
>>>>> http://groovy.codehaus.org/groovy-jdk/java/util/Collection.html is not
>>>>> enabled. That means that you cannot easily navigate from Collection to List
>>>>> to ... I would love to see that fixed!
>>>>
>>>>
>>>> Could you please file a JIRA issue for that one?
>>>>
>>>>>
>>>>> But of course: the fact that the documentation is inadequate doesn't
>>>>> mean that Groovy is!
>>>>
>>>>
>>>> Hehe, sure!
>>>> Thanks for saying it :-)
>>>>
>>>> Guillaume
>>>>
>>>>>
>>>>> /\/\orten
>>>>>
>>>>>
>>>>> On Fri, Feb 8, 2013 at 2:31 PM, Guillaume Laforge <[hidden email]>
>>>>> wrote:
>>>>>>
>>>>>> Hi all,
>>>>>>
>>>>>> Groovy is a very mature and widely used language on the Java platform,
>>>>>> with hundred thousands of developers worldwide.
>>>>>> It's stable and fast, flexible and readable, has got plenty of
>>>>>> interesting use cases (DSLs, testing...), is feature-packed, and it's got a
>>>>>> very rich ecosystem of successful projects (Grails, Gradle, Griffon, Spock,
>>>>>> Geb, Gaelyk, to name but a few)
>>>>>>
>>>>>> However, one area where the Groovy project can do better is with its
>>>>>> documentation.
>>>>>>
>>>>>> For instance, if you read the recent DrDobbs editorial, there were some
>>>>>> valid points made on this topic. And it's true that our documentation can be
>>>>>> greatly improved.
>>>>>>
>>>>>> Despite its 1000+ pages of wiki content, it's hard to find the
>>>>>> information you're looking for, it's of very uneven quality and style, lots
>>>>>> of pages are outdated or show samples with mistakes in them, and there are
>>>>>> also holes for features not covered or not explained in details.
>>>>>>
>>>>>> We're launching an effort towards overhauling our documentation and web
>>>>>> presence.
>>>>>>
>>>>>> And I'd love if you could take part in that effort, even if only by
>>>>>> telling us about your expectations regarding the website, the documentation,
>>>>>> etc., or even by helping us authoring content, of course.
>>>>>>
>>>>>>
>>>>>> For the website, we'll need a fresh new skin, modern and sexy, that
>>>>>> makes visitors want to learn more about Groovy and try it.
>>>>>> We should be able to easily add sections as we progress along its
>>>>>> rework, so as to be able to later publish case studies, testimonials,
>>>>>> interactive tutorials, screencasts, news, events, jobs, etc.
>>>>>> We're interested in what you would like to see on the front page when
>>>>>> you land on the Groovy website, how you would like the site to be organized,
>>>>>> etc.
>>>>>>
>>>>>> If you have ideas of sites whose design inspire you, please don't
>>>>>> hesitate to share them.
>>>>>> Also don't hesitate to tell us what kind of sections or content you'd
>>>>>> like to see showcased on the site.
>>>>>>
>>>>>>
>>>>>> For the documentation, we need to start anew, even if there's
>>>>>> definitely content and examples we can take inspiration from from our
>>>>>> current wiki.
>>>>>>
>>>>>> The documentation should be versioned, so that we don't have to ask
>>>>>> ourselves from which version this or that feature is available. It also
>>>>>> means we should be able to host it alongside our source code, so as to tie
>>>>>> the documentation with its code version and be bundled easily when we do our
>>>>>> releases.
>>>>>> Visitors will be able to navigate to the "latest" version or to some
>>>>>> older versions (usually the latest update of a given branch, like 1.8.9,
>>>>>> 2.0.6, 2.1.0, etc...)
>>>>>>
>>>>>> It should also be possible to download it from the website, in HTML at
>>>>>> least, but ideally also in PDF form.
>>>>>> If you have some best practices for PDF conversion, we're also happy to
>>>>>> hear your thoughts.
>>>>>>
>>>>>> The original format of documentation will likely be in Markdown, as
>>>>>> it's a format which is well supported by text editors, IDEs and tools.
>>>>>> A nice benefit too, is it's automatically rendered on Github where the
>>>>>> Groovy sources are hosted, which also means that it should be easy for
>>>>>> contributors to fork and edit the documentation on spot, through the Github
>>>>>> interface.
>>>>>>
>>>>>> The documentation should also be executable, in the sense that we can
>>>>>> run the examples as unit tests, as part of our build, so as to ensure that
>>>>>> the embedded samples are always in sync with our codebase, thus ensuring
>>>>>> that the documentation is properly up-to-date.
>>>>>> For that purpose, I've been toying on-and-off on an executable
>>>>>> documentation tool, that consumes some wiki markup (not yet Markdown but
>>>>>> I'll migrate), that extracts the code samples and run them as unit tests.
>>>>>> I'm intending to use that tool for our executable documentation.
>>>>>> It's not yet ready, but for those interested in contributing, I'm happy
>>>>>> to discuss how we can evolve it for our use.
>>>>>>
>>>>>>
>>>>>> Documenting the language and its libraries with nice narrative and
>>>>>> examples is one thing, but there's also the JavaDoc / GroovyDoc
>>>>>> documentation!
>>>>>> Our GroovyDoc, in particular, looks like the old JavaDoc format, not
>>>>>> very sexy or appealing.
>>>>>> It'd be nice if the look'n feel of the GroovyDoc was sexier and that it
>>>>>> looked coherent with the website redesign, sharing the same style.
>>>>>>
>>>>>> Also, we should make it a little bit more dynamic (the ScalaDoc is a
>>>>>> great example of that), so that it's possible to search classes or methods
>>>>>> through JavaScript.
>>>>>> It's also an area where you can participate, in particular if you've
>>>>>> got some JavaScript ninja skills, it might be a nice contribution too.
>>>>>>
>>>>>> One last aspect to consider also here, is with the Groovy JDK methods
>>>>>> (or also with your own extension modules).
>>>>>> We're wondering how to somehow decorate an existing API or the JDK
>>>>>> itself with methods added by Groovy or your own modules.
>>>>>> How to best represent that in the context of your JavaDoc/GroovyDoc, or
>>>>>> layered on top of the JDK documentation (but copyright issues apply...)
>>>>>> We'd be happy to hear your thoughts about that.
>>>>>>
>>>>>>
>>>>>> Well, that was a long email, and there are plenty more ideas and open
>>>>>> questions that I could share with you on this big and important topic. But I
>>>>>> wanted to start a discussion with you all about this initiative, to hear
>>>>>> your feedback.
>>>>>> Then we'll derive a more actionable list of things to do to achieve the
>>>>>> overall goal as we progress along!
>>>>>>
>>>>>> Thanks a lot for your attention, if you've read through all this, and
>>>>>> I'm looking forward to hearing from you!
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Guillaume Laforge
>>>>>> Groovy Project Manager
>>>>>> SpringSource, a division of VMware
>>>>>>
>>>>>> Blog: http://glaforge.appspot.com/
>>>>>> Social: @glaforge / Google+
>>>>>
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Guillaume Laforge
>>>> Groovy Project Manager
>>>> Head of Groovy Development at SpringSource
>>>> http://www.springsource.com/g2one
>>>
>>>
>>
>>
>>
>> --
>> Guillaume Laforge
>> Groovy Project Manager
>> Head of Groovy Development at SpringSource
>> http://www.springsource.com/g2one
>
>
>
> --
> Andrey Bloschetsov
>
> ---------------------------------------------------------------------
> 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





--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Russel Winder-3
In reply to this post by Guillaume Laforge-4
Guillaume,

On Mon, 2013-02-11 at 16:30 +0100, Guillaume Laforge wrote:

> Hi Andrey,
>
> DocBook is an option.
>
> A great advantage of DocBook, I think, is how it's already ready for
> producing single-page and multi-page HTML documentation, as well as PDF
> outputs -- although I haven't looked at how friendly / customizable this is.
>
> The drawback though might be more around the fact it's a bit painful to
> work with XML these days, and apart from the Xmlmind tool (if I recall the
> name correctly), the tooling isn't too friendly for authoring content.
All true. XML is not a format for human authoring unless you really,
really, really, have to.

> With doc in Markdown format, they'd appear nicely on Github. And it'd be
> easy for people to edit / fork live on Github to fix obvious typos or
> contribute changes (and visualize them easily on spot without requiring
> actually "building" the output)
> Many tools know how to grok that syntax nowadays (from Vim to IDEs, as well
> as dedicated tools like Mou on macs).
> There's a great Java library for Markdown which also understands several
> extensions to the basic Markdown syntax (the Pegdown library on Github).
> With the parser, I can easily retrieve the code snippets so as to turn them
> into executable tests (I could certainly do that with Docbook's XML as
> well, if I can extend it with my own attributes or piggyback on existing
> ones).
>
> With Markdown however, there's just the HTML output, and nothing
> out-of-the-box for different formats (multi vs single page), or for PDF
> output.
You could use the Pandoc system to generate LaTeX and thence use XeLaTeX
to generate PDF.

--
Russel.
=============================================================================
Dr Russel Winder      t: +44 20 7585 2200   voip: sip:[hidden email]
41 Buckmaster Road    m: +44 7770 465 077   xmpp: [hidden email]
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

catalan42
In reply to this post by Guillaume Laforge-4
I agree that Markdown is very user-friendly, especially for first-time
contributors.   :)
Alan

On Mon, Feb 11, 2013 at 7:36 AM, Guillaume Laforge
<[hidden email]> wrote:

> Right, Gradle went with Docbook, as far as I can see, and I think they added
> some layer for testing some of the snippets of code that are contained in
> the documentation.
>
> The "executable" aspect is important in my opinion, to keep the
> documentation as "alive" as possible, avoiding becoming out-dated quickly.
>
> But well, I'm not too fond of using XML for the documentation :-(
>
>
> On Fri, Feb 8, 2013 at 7:26 PM, Scott Hickey <[hidden email]> wrote:
>>
>> iirc, Hans has a nice documentation system as part of Gradle as well.
>>
>> Scott Hickey
>>
>> On Fri, Feb 8, 2013 at 12:17 PM, Andrey Bloschetsov
>> <[hidden email]> wrote:
>> > The Springsource documentation is very usable and clear. For creating
>> > they using DocBook format it is a special format for technical
>> > documentation (http://en.wikipedia.org/wiki/DocBook).
>> >
>> > Spring Framework documentation source:
>> >
>> > https://github.com/SpringSource/spring-framework/tree/3.2.x/src/reference/docbook
>> >
>> > Spring Framework documentation in HTML:
>> >
>> > http://static.springsource.org/spring/docs/3.2.x/spring-framework-reference/html/
>> >
>> > 2013/2/8 Guillaume Laforge <[hidden email]>:
>> >> Thanks!
>> >>
>> >>
>> >> On Fri, Feb 8, 2013 at 3:31 PM, Morten Hindsholm <[hidden email]>
>> >> wrote:
>> >>>
>> >>> JIRA created: http://jira.codehaus.org/browse/GROOVY-5983
>> >>>
>> >>> /\/\orten
>> >>>
>> >>>
>> >>> On Fri, Feb 8, 2013 at 3:20 PM, Guillaume Laforge
>> >>> <[hidden email]>
>> >>> wrote:
>> >>>>
>> >>>> Hi Morten,
>> >>>>
>> >>>> On Fri, Feb 8, 2013 at 3:10 PM, Morten Hindsholm
>> >>>> <[hidden email]>
>> >>>> wrote:
>> >>>>>
>> >>>>> Improving the documentation is indeed a good idea. I tend to use
>> >>>>> Google
>> >>>>> as the main entry point for looking up Groovy details, but a
>> >>>>> well-structured
>> >>>>> documentation site would definitely be better.
>> >>>>>
>> >>>>> Regarding styling etc I like the Grails documentation and I think it
>> >>>>> might be used as inspiration.
>> >>>>>
>> >>>>> And the number one issue I am having with the current GroovyDoc: The
>> >>>>> 'package' link on pages like this
>> >>>>> http://groovy.codehaus.org/groovy-jdk/java/util/Collection.html is
>> >>>>> not
>> >>>>> enabled. That means that you cannot easily navigate from Collection
>> >>>>> to List
>> >>>>> to ... I would love to see that fixed!
>> >>>>
>> >>>>
>> >>>> Could you please file a JIRA issue for that one?
>> >>>>
>> >>>>>
>> >>>>> But of course: the fact that the documentation is inadequate doesn't
>> >>>>> mean that Groovy is!
>> >>>>
>> >>>>
>> >>>> Hehe, sure!
>> >>>> Thanks for saying it :-)
>> >>>>
>> >>>> Guillaume
>> >>>>
>> >>>>>
>> >>>>> /\/\orten
>> >>>>>
>> >>>>>
>> >>>>> On Fri, Feb 8, 2013 at 2:31 PM, Guillaume Laforge
>> >>>>> <[hidden email]>
>> >>>>> wrote:
>> >>>>>>
>> >>>>>> Hi all,
>> >>>>>>
>> >>>>>> Groovy is a very mature and widely used language on the Java
>> >>>>>> platform,
>> >>>>>> with hundred thousands of developers worldwide.
>> >>>>>> It's stable and fast, flexible and readable, has got plenty of
>> >>>>>> interesting use cases (DSLs, testing...), is feature-packed, and
>> >>>>>> it's got a
>> >>>>>> very rich ecosystem of successful projects (Grails, Gradle,
>> >>>>>> Griffon, Spock,
>> >>>>>> Geb, Gaelyk, to name but a few)
>> >>>>>>
>> >>>>>> However, one area where the Groovy project can do better is with
>> >>>>>> its
>> >>>>>> documentation.
>> >>>>>>
>> >>>>>> For instance, if you read the recent DrDobbs editorial, there were
>> >>>>>> some
>> >>>>>> valid points made on this topic. And it's true that our
>> >>>>>> documentation can be
>> >>>>>> greatly improved.
>> >>>>>>
>> >>>>>> Despite its 1000+ pages of wiki content, it's hard to find the
>> >>>>>> information you're looking for, it's of very uneven quality and
>> >>>>>> style, lots
>> >>>>>> of pages are outdated or show samples with mistakes in them, and
>> >>>>>> there are
>> >>>>>> also holes for features not covered or not explained in details.
>> >>>>>>
>> >>>>>> We're launching an effort towards overhauling our documentation and
>> >>>>>> web
>> >>>>>> presence.
>> >>>>>>
>> >>>>>> And I'd love if you could take part in that effort, even if only by
>> >>>>>> telling us about your expectations regarding the website, the
>> >>>>>> documentation,
>> >>>>>> etc., or even by helping us authoring content, of course.
>> >>>>>>
>> >>>>>>
>> >>>>>> For the website, we'll need a fresh new skin, modern and sexy, that
>> >>>>>> makes visitors want to learn more about Groovy and try it.
>> >>>>>> We should be able to easily add sections as we progress along its
>> >>>>>> rework, so as to be able to later publish case studies,
>> >>>>>> testimonials,
>> >>>>>> interactive tutorials, screencasts, news, events, jobs, etc.
>> >>>>>> We're interested in what you would like to see on the front page
>> >>>>>> when
>> >>>>>> you land on the Groovy website, how you would like the site to be
>> >>>>>> organized,
>> >>>>>> etc.
>> >>>>>>
>> >>>>>> If you have ideas of sites whose design inspire you, please don't
>> >>>>>> hesitate to share them.
>> >>>>>> Also don't hesitate to tell us what kind of sections or content
>> >>>>>> you'd
>> >>>>>> like to see showcased on the site.
>> >>>>>>
>> >>>>>>
>> >>>>>> For the documentation, we need to start anew, even if there's
>> >>>>>> definitely content and examples we can take inspiration from from
>> >>>>>> our
>> >>>>>> current wiki.
>> >>>>>>
>> >>>>>> The documentation should be versioned, so that we don't have to ask
>> >>>>>> ourselves from which version this or that feature is available. It
>> >>>>>> also
>> >>>>>> means we should be able to host it alongside our source code, so as
>> >>>>>> to tie
>> >>>>>> the documentation with its code version and be bundled easily when
>> >>>>>> we do our
>> >>>>>> releases.
>> >>>>>> Visitors will be able to navigate to the "latest" version or to
>> >>>>>> some
>> >>>>>> older versions (usually the latest update of a given branch, like
>> >>>>>> 1.8.9,
>> >>>>>> 2.0.6, 2.1.0, etc...)
>> >>>>>>
>> >>>>>> It should also be possible to download it from the website, in HTML
>> >>>>>> at
>> >>>>>> least, but ideally also in PDF form.
>> >>>>>> If you have some best practices for PDF conversion, we're also
>> >>>>>> happy to
>> >>>>>> hear your thoughts.
>> >>>>>>
>> >>>>>> The original format of documentation will likely be in Markdown, as
>> >>>>>> it's a format which is well supported by text editors, IDEs and
>> >>>>>> tools.
>> >>>>>> A nice benefit too, is it's automatically rendered on Github where
>> >>>>>> the
>> >>>>>> Groovy sources are hosted, which also means that it should be easy
>> >>>>>> for
>> >>>>>> contributors to fork and edit the documentation on spot, through
>> >>>>>> the Github
>> >>>>>> interface.
>> >>>>>>
>> >>>>>> The documentation should also be executable, in the sense that we
>> >>>>>> can
>> >>>>>> run the examples as unit tests, as part of our build, so as to
>> >>>>>> ensure that
>> >>>>>> the embedded samples are always in sync with our codebase, thus
>> >>>>>> ensuring
>> >>>>>> that the documentation is properly up-to-date.
>> >>>>>> For that purpose, I've been toying on-and-off on an executable
>> >>>>>> documentation tool, that consumes some wiki markup (not yet
>> >>>>>> Markdown but
>> >>>>>> I'll migrate), that extracts the code samples and run them as unit
>> >>>>>> tests.
>> >>>>>> I'm intending to use that tool for our executable documentation.
>> >>>>>> It's not yet ready, but for those interested in contributing, I'm
>> >>>>>> happy
>> >>>>>> to discuss how we can evolve it for our use.
>> >>>>>>
>> >>>>>>
>> >>>>>> Documenting the language and its libraries with nice narrative and
>> >>>>>> examples is one thing, but there's also the JavaDoc / GroovyDoc
>> >>>>>> documentation!
>> >>>>>> Our GroovyDoc, in particular, looks like the old JavaDoc format,
>> >>>>>> not
>> >>>>>> very sexy or appealing.
>> >>>>>> It'd be nice if the look'n feel of the GroovyDoc was sexier and
>> >>>>>> that it
>> >>>>>> looked coherent with the website redesign, sharing the same style.
>> >>>>>>
>> >>>>>> Also, we should make it a little bit more dynamic (the ScalaDoc is
>> >>>>>> a
>> >>>>>> great example of that), so that it's possible to search classes or
>> >>>>>> methods
>> >>>>>> through JavaScript.
>> >>>>>> It's also an area where you can participate, in particular if
>> >>>>>> you've
>> >>>>>> got some JavaScript ninja skills, it might be a nice contribution
>> >>>>>> too.
>> >>>>>>
>> >>>>>> One last aspect to consider also here, is with the Groovy JDK
>> >>>>>> methods
>> >>>>>> (or also with your own extension modules).
>> >>>>>> We're wondering how to somehow decorate an existing API or the JDK
>> >>>>>> itself with methods added by Groovy or your own modules.
>> >>>>>> How to best represent that in the context of your
>> >>>>>> JavaDoc/GroovyDoc, or
>> >>>>>> layered on top of the JDK documentation (but copyright issues
>> >>>>>> apply...)
>> >>>>>> We'd be happy to hear your thoughts about that.
>> >>>>>>
>> >>>>>>
>> >>>>>> Well, that was a long email, and there are plenty more ideas and
>> >>>>>> open
>> >>>>>> questions that I could share with you on this big and important
>> >>>>>> topic. But I
>> >>>>>> wanted to start a discussion with you all about this initiative, to
>> >>>>>> hear
>> >>>>>> your feedback.
>> >>>>>> Then we'll derive a more actionable list of things to do to achieve
>> >>>>>> the
>> >>>>>> overall goal as we progress along!
>> >>>>>>
>> >>>>>> Thanks a lot for your attention, if you've read through all this,
>> >>>>>> and
>> >>>>>> I'm looking forward to hearing from you!
>> >>>>>>
>> >>>>>>
>> >>>>>> --
>> >>>>>> Guillaume Laforge
>> >>>>>> Groovy Project Manager
>> >>>>>> SpringSource, a division of VMware
>> >>>>>>
>> >>>>>> Blog: http://glaforge.appspot.com/
>> >>>>>> Social: @glaforge / Google+
>> >>>>>
>> >>>>>
>> >>>>
>> >>>>
>> >>>>
>> >>>> --
>> >>>> Guillaume Laforge
>> >>>> Groovy Project Manager
>> >>>> Head of Groovy Development at SpringSource
>> >>>> http://www.springsource.com/g2one
>> >>>
>> >>>
>> >>
>> >>
>> >>
>> >> --
>> >> Guillaume Laforge
>> >> Groovy Project Manager
>> >> Head of Groovy Development at SpringSource
>> >> http://www.springsource.com/g2one
>> >
>> >
>> >
>> > --
>> > Andrey Bloschetsov
>> >
>> > ---------------------------------------------------------------------
>> > 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
>>
>>
>
>
>
> --
> Guillaume Laforge
> Groovy Project Manager
> Head of Groovy Development at SpringSource
> http://www.springsource.com/g2one

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

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
In reply to this post by Russel Winder-3

On Fri, Feb 8, 2013 at 7:33 PM, Russel Winder <[hidden email]> wrote:
On Fri, 2013-02-08 at 12:26 -0600, Scott Hickey wrote:
> iirc, Hans has a nice documentation system as part of Gradle as well.

Isn't that GrailsDoc? If not then yes, it is an option, as is GrailsDoc.

GrailsDoc currently doesn't have embedded snippets of code that are testable. That'd need adding.
Also, it's still using the old Radeox library for the markup and rendering, which is not ideal, as the library is not maintained, is not necessarily a well known syntax, is not recognized by Github, and also the Groovy syntax rendering is not correct.
 
Docbook/XML is a (more or less) reasonably tool chain especially if you
want to generate PDF as well as HTML. Markdown is only really good for
generating HTML, unless you want to get into serious Pandoc and LaTeX
hacking. XeLaTeX is great but only really for us folks that like LaTeX.

If we go with LaTeX, Russel volunteers to write the whole documentation with it :-)
So we should go with it ;-)))

Guillaume
 

--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
In reply to this post by Russel Winder-3

On Mon, Feb 11, 2013 at 4:40 PM, Russel Winder <[hidden email]> wrote:
[...]
> With Markdown however, there's just the HTML output, and nothing
> out-of-the-box for different formats (multi vs single page), or for PDF
> output.

You could use the Pandoc system to generate LaTeX and thence use XeLaTeX
to generate PDF.

I've heard of Pandoc, but haven't investigated it further for now. 
It's worth a look.
Thanks for reminding me about it.

--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
In reply to this post by chiquitinxx
Hi Jorge,

On Fri, Feb 8, 2013 at 7:42 PM, Jorge Franco Leza <[hidden email]> wrote:
Hello!

I miss a good screencast, at main page, showing the Groovy power in 5 - 10 mins.

Yup, I think it'd be nice to have a few samples and/or mini screencast to give a test of Groovy at first sight.
Perhaps a kind of "carousel" showing those few samples or screencasts, to have a few different examples rotating.
 
Awesome sites for beginners as Code School tryruby.org

I'd like to have some runnable code samples, somehow integrating something like the Groovy Web Console (http://groovyconsole.appspot.com/) but somehow built-in the site.

I also like interactive tutorials like the ones you can see on the Knockout.JS framework:
It's very nice and effective!

But well, of course, such things can't be done all right away, and we can add "features" to the website as we progress along :-)
 
And for me, the best documentation is the faster and complete, faster like google suggestions while typing, and complete with all groovy resources in the web. Boring navigate in google to search for a groovy specific topic. For example typing "collect", before press enter, showing me:

Api: List.collect()
Screencast: Collections in Groovy
Doc: Using collections
Example: Converting lists
Article: Groovy love collections
Stackoverflow: groovy list collect
Haki: list goodness
....

I mean, not only search text in groovy doc, too search in screencasts, examples, groovy blogs. And do it fast.
So, all groovy info is in Groovy Site, and the best place for get groovy info is the groovy site. Not easy sure, but very cool :)

Some kind of "faceted" search would be nice (think ElasticSearch for example).
It's not necessarily very easy to do that nicely I guess, but it could also be an incremental improvement to the site.
Currently, Google Custom Search is doing the job, although it's not really categorizing the different kind of results we get, but it's something we could add afterwards too.
But I think we need to write some content first, so the search engine has something to search for :-)
But I definitely like your idea.

Guillaume
 

El 08/02/2013, a las 19:26, Scott Hickey escribió:

> iirc, Hans has a nice documentation system as part of Gradle as well.
>
> Scott Hickey
>
> On Fri, Feb 8, 2013 at 12:17 PM, Andrey Bloschetsov
> <[hidden email]> wrote:
>> The Springsource documentation is very usable and clear. For creating
>> they using DocBook format it is a special format for technical
>> documentation (http://en.wikipedia.org/wiki/DocBook).
>>
>> Spring Framework documentation source:
>> https://github.com/SpringSource/spring-framework/tree/3.2.x/src/reference/docbook
>>
>> Spring Framework documentation in HTML:
>> http://static.springsource.org/spring/docs/3.2.x/spring-framework-reference/html/
>>
>> 2013/2/8 Guillaume Laforge <[hidden email]>:
>>> Thanks!
>>>
>>>
>>> On Fri, Feb 8, 2013 at 3:31 PM, Morten Hindsholm <[hidden email]>
>>> wrote:
>>>>
>>>> JIRA created: http://jira.codehaus.org/browse/GROOVY-5983
>>>>
>>>> /\/\orten
>>>>
>>>>
>>>> On Fri, Feb 8, 2013 at 3:20 PM, Guillaume Laforge <[hidden email]>
>>>> wrote:
>>>>>
>>>>> Hi Morten,
>>>>>
>>>>> On Fri, Feb 8, 2013 at 3:10 PM, Morten Hindsholm <[hidden email]>
>>>>> wrote:
>>>>>>
>>>>>> Improving the documentation is indeed a good idea. I tend to use Google
>>>>>> as the main entry point for looking up Groovy details, but a well-structured
>>>>>> documentation site would definitely be better.
>>>>>>
>>>>>> Regarding styling etc I like the Grails documentation and I think it
>>>>>> might be used as inspiration.
>>>>>>
>>>>>> And the number one issue I am having with the current GroovyDoc: The
>>>>>> 'package' link on pages like this
>>>>>> http://groovy.codehaus.org/groovy-jdk/java/util/Collection.html is not
>>>>>> enabled. That means that you cannot easily navigate from Collection to List
>>>>>> to ... I would love to see that fixed!
>>>>>
>>>>>
>>>>> Could you please file a JIRA issue for that one?
>>>>>
>>>>>>
>>>>>> But of course: the fact that the documentation is inadequate doesn't
>>>>>> mean that Groovy is!
>>>>>
>>>>>
>>>>> Hehe, sure!
>>>>> Thanks for saying it :-)
>>>>>
>>>>> Guillaume
>>>>>
>>>>>>
>>>>>> /\/\orten
>>>>>>
>>>>>>
>>>>>> On Fri, Feb 8, 2013 at 2:31 PM, Guillaume Laforge <[hidden email]>
>>>>>> wrote:
>>>>>>>
>>>>>>> Hi all,
>>>>>>>
>>>>>>> Groovy is a very mature and widely used language on the Java platform,
>>>>>>> with hundred thousands of developers worldwide.
>>>>>>> It's stable and fast, flexible and readable, has got plenty of
>>>>>>> interesting use cases (DSLs, testing...), is feature-packed, and it's got a
>>>>>>> very rich ecosystem of successful projects (Grails, Gradle, Griffon, Spock,
>>>>>>> Geb, Gaelyk, to name but a few)
>>>>>>>
>>>>>>> However, one area where the Groovy project can do better is with its
>>>>>>> documentation.
>>>>>>>
>>>>>>> For instance, if you read the recent DrDobbs editorial, there were some
>>>>>>> valid points made on this topic. And it's true that our documentation can be
>>>>>>> greatly improved.
>>>>>>>
>>>>>>> Despite its 1000+ pages of wiki content, it's hard to find the
>>>>>>> information you're looking for, it's of very uneven quality and style, lots
>>>>>>> of pages are outdated or show samples with mistakes in them, and there are
>>>>>>> also holes for features not covered or not explained in details.
>>>>>>>
>>>>>>> We're launching an effort towards overhauling our documentation and web
>>>>>>> presence.
>>>>>>>
>>>>>>> And I'd love if you could take part in that effort, even if only by
>>>>>>> telling us about your expectations regarding the website, the documentation,
>>>>>>> etc., or even by helping us authoring content, of course.
>>>>>>>
>>>>>>>
>>>>>>> For the website, we'll need a fresh new skin, modern and sexy, that
>>>>>>> makes visitors want to learn more about Groovy and try it.
>>>>>>> We should be able to easily add sections as we progress along its
>>>>>>> rework, so as to be able to later publish case studies, testimonials,
>>>>>>> interactive tutorials, screencasts, news, events, jobs, etc.
>>>>>>> We're interested in what you would like to see on the front page when
>>>>>>> you land on the Groovy website, how you would like the site to be organized,
>>>>>>> etc.
>>>>>>>
>>>>>>> If you have ideas of sites whose design inspire you, please don't
>>>>>>> hesitate to share them.
>>>>>>> Also don't hesitate to tell us what kind of sections or content you'd
>>>>>>> like to see showcased on the site.
>>>>>>>
>>>>>>>
>>>>>>> For the documentation, we need to start anew, even if there's
>>>>>>> definitely content and examples we can take inspiration from from our
>>>>>>> current wiki.
>>>>>>>
>>>>>>> The documentation should be versioned, so that we don't have to ask
>>>>>>> ourselves from which version this or that feature is available. It also
>>>>>>> means we should be able to host it alongside our source code, so as to tie
>>>>>>> the documentation with its code version and be bundled easily when we do our
>>>>>>> releases.
>>>>>>> Visitors will be able to navigate to the "latest" version or to some
>>>>>>> older versions (usually the latest update of a given branch, like 1.8.9,
>>>>>>> 2.0.6, 2.1.0, etc...)
>>>>>>>
>>>>>>> It should also be possible to download it from the website, in HTML at
>>>>>>> least, but ideally also in PDF form.
>>>>>>> If you have some best practices for PDF conversion, we're also happy to
>>>>>>> hear your thoughts.
>>>>>>>
>>>>>>> The original format of documentation will likely be in Markdown, as
>>>>>>> it's a format which is well supported by text editors, IDEs and tools.
>>>>>>> A nice benefit too, is it's automatically rendered on Github where the
>>>>>>> Groovy sources are hosted, which also means that it should be easy for
>>>>>>> contributors to fork and edit the documentation on spot, through the Github
>>>>>>> interface.
>>>>>>>
>>>>>>> The documentation should also be executable, in the sense that we can
>>>>>>> run the examples as unit tests, as part of our build, so as to ensure that
>>>>>>> the embedded samples are always in sync with our codebase, thus ensuring
>>>>>>> that the documentation is properly up-to-date.
>>>>>>> For that purpose, I've been toying on-and-off on an executable
>>>>>>> documentation tool, that consumes some wiki markup (not yet Markdown but
>>>>>>> I'll migrate), that extracts the code samples and run them as unit tests.
>>>>>>> I'm intending to use that tool for our executable documentation.
>>>>>>> It's not yet ready, but for those interested in contributing, I'm happy
>>>>>>> to discuss how we can evolve it for our use.
>>>>>>>
>>>>>>>
>>>>>>> Documenting the language and its libraries with nice narrative and
>>>>>>> examples is one thing, but there's also the JavaDoc / GroovyDoc
>>>>>>> documentation!
>>>>>>> Our GroovyDoc, in particular, looks like the old JavaDoc format, not
>>>>>>> very sexy or appealing.
>>>>>>> It'd be nice if the look'n feel of the GroovyDoc was sexier and that it
>>>>>>> looked coherent with the website redesign, sharing the same style.
>>>>>>>
>>>>>>> Also, we should make it a little bit more dynamic (the ScalaDoc is a
>>>>>>> great example of that), so that it's possible to search classes or methods
>>>>>>> through JavaScript.
>>>>>>> It's also an area where you can participate, in particular if you've
>>>>>>> got some JavaScript ninja skills, it might be a nice contribution too.
>>>>>>>
>>>>>>> One last aspect to consider also here, is with the Groovy JDK methods
>>>>>>> (or also with your own extension modules).
>>>>>>> We're wondering how to somehow decorate an existing API or the JDK
>>>>>>> itself with methods added by Groovy or your own modules.
>>>>>>> How to best represent that in the context of your JavaDoc/GroovyDoc, or
>>>>>>> layered on top of the JDK documentation (but copyright issues apply...)
>>>>>>> We'd be happy to hear your thoughts about that.
>>>>>>>
>>>>>>>
>>>>>>> Well, that was a long email, and there are plenty more ideas and open
>>>>>>> questions that I could share with you on this big and important topic. But I
>>>>>>> wanted to start a discussion with you all about this initiative, to hear
>>>>>>> your feedback.
>>>>>>> Then we'll derive a more actionable list of things to do to achieve the
>>>>>>> overall goal as we progress along!
>>>>>>>
>>>>>>> Thanks a lot for your attention, if you've read through all this, and
>>>>>>> I'm looking forward to hearing from you!
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Guillaume Laforge
>>>>>>> Groovy Project Manager
>>>>>>> SpringSource, a division of VMware
>>>>>>>
>>>>>>> Blog: http://glaforge.appspot.com/
>>>>>>> Social: @glaforge / Google+
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Guillaume Laforge
>>>>> Groovy Project Manager
>>>>> Head of Groovy Development at SpringSource
>>>>> http://www.springsource.com/g2one
>>>>
>>>>
>>>
>>>
>>>
>>> --
>>> Guillaume Laforge
>>> Groovy Project Manager
>>> Head of Groovy Development at SpringSource
>>> http://www.springsource.com/g2one
>>
>>
>>
>> --
>> Andrey Bloschetsov
>>
>> ---------------------------------------------------------------------
>> 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
>
>


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

    http://xircles.codehaus.org/manage_email





--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Russel Winder-3
In reply to this post by Guillaume Laforge-4
On Mon, 2013-02-11 at 16:44 +0100, Guillaume Laforge wrote:
[…]
> GrailsDoc currently doesn't have embedded snippets of code that are
> testable. That'd need adding.
> Also, it's still using the old Radeox library for the markup and rendering,
> which is not ideal, as the library is not maintained, is not necessarily a
> well known syntax, is not recognized by Github, and also the Groovy syntax
> rendering is not correct.

My personal experience with GrailsDoc for the GPars documentation is
that I would prefer to use ReStructured Text, Markdown, LaTeX,
Docbook/XML, anything but…

> If we go with LaTeX, Russel volunteers to write the whole documentation
> with it :-)
> So we should go with it ;-)))

Someone would need to find some dosh to pay me for that. As a 1 person
task it is a full time job. For a bunch of volunteers we need 50+ people
all chipping in on their free time. Or better still people chipping in
on company time allowed actively, indeed supported, by their company.

--
Russel.
=============================================================================
Dr Russel Winder      t: +44 20 7585 2200   voip: sip:[hidden email]
41 Buckmaster Road    m: +44 7770 465 077   xmpp: [hidden email]
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Russel Winder-3
In reply to this post by Guillaume Laforge-4
On Mon, 2013-02-11 at 16:45 +0100, Guillaume Laforge wrote:
[…]
> I've heard of Pandoc, but haven't investigated it further for now.
> It's worth a look.
> Thanks for reminding me about it.

Markdown appears to have no way of doing contents or indexes. Pandoc to
LaTeX get the ability to create a contents but not an index.

--
Russel.
=============================================================================
Dr Russel Winder      t: +44 20 7585 2200   voip: sip:[hidden email]
41 Buckmaster Road    m: +44 7770 465 077   xmpp: [hidden email]
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder

signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
In reply to this post by Russel Winder-3

On Mon, Feb 11, 2013 at 5:03 PM, Russel Winder <[hidden email]> wrote:
[...]
My personal experience with GrailsDoc for the GPars documentation is
that I would prefer to use ReStructured Text, Markdown, LaTeX,
Docbook/XML, anything but…

Good to know :-)
I had forgotten about ReStructured Text. Is there a good Java parser for that?
I fear LaTeX and DocBook would be a bit too painful :-(
 
> If we go with LaTeX, Russel volunteers to write the whole documentation
> with it :-)
> So we should go with it ;-)))

Someone would need to find some dosh to pay me for that. As a 1 person
task it is a full time job. For a bunch of volunteers we need 50+ people
all chipping in on their free time. Or better still people chipping in
on company time allowed actively, indeed supported, by their company.

I was kidding for your volunteering with LaTeX ;-)

What I'm looking forward to do, actually, is to craft an outline of the documentation, hence listing all of the Groovy syntax and capabilities.
That way, it'd serve as a first table of content, that would could progressively flesh out.
And volunteers interested in helping with one particular section or topic can chime in and start contributing right away.

Because, well, for getting help, we need to ask for it properly, and if we don't tell contributors how and where they can contribute, we can't get much contribution going on otherwise :-)
 
--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one
123456