[ANN] Documentation effort and site redesign

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 Christian,

On Mon, Apr 22, 2013 at 2:34 PM, ChrLipp <[hidden email]> wrote:
I would appreciate if you choose AsciDoc(tor). I didn't know the gradle
plugin and did already some tests over the weekend. A zero installation
build - having just to execute 'gradlew' - is a huge advantage.

Exactly, I don't want us all to have to install special tooling on our machines.
I want the build to Just Work (TM) out of the box by running ./gradlew :-) 

The gradle plugin might need some update soon, to be able to pass particular parameters to AsciiDoctor, but we know the guys behind the plugin (Andrés for instance, and Benjamin, I believe). So we can get their help there.

And I'm also waiting on some new features in the next release of AsciiDoctor (that should take place this week), which allows to use AsciiDoc's docinfo stuff to be able to customize headers (so as to publish the doc on the website w/ a different look than when bundling the doc in the distribution, etc), or to be able to include just parts of scripts to have a nicer narrative while still being able to externalize the scripts to run them as unit tests (still with my obsession of having "executable specification" for Groovy).

So all in all, AsciiDoctor is looking great for our requirements :-)

There are a lot of books written in AsciiDoc, see
http://www.methods.co.nz/asciidoc/index.html#X6
Matt Neuburg describes his toolchain (on Mac) here:
http://www.apeth.net/matt/iosbooktoolchain.html

And since the output is DocBook I will be able to port it to epub. Prepare
to receive a pull request :-)

Ah good to know we have the knowledge available around!
I'm looking forward to collaborating with you on that soon!

Guillaume
 
Regards, Christian



--
View this message in context: http://groovy.329449.n5.nabble.com/ANN-Documentation-effort-and-site-redesign-tp5712875p5715126.html
Sent from the groovy - user mailing list archive at Nabble.com.

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

Steve Amerige
In reply to this post by Guillaume Laforge
I'm very glad to hear that documentation might become a priority.  I think it is important to note that there are at least two kinds of documentation:

1. E-Learning Documentation
2. Reference Documentation

E-Learning Documentation has the goal of providing progressive training on a whole subject area.  As such, it is usually organized as a sequence of lessons in which concepts are introduced first, and then built upon.  In addition, as the goal is training, examples and best practices are included.  The organization of the E-Learning Documentation User Experience is based on Concept and Usefulness ordering.

Reference Documentation has the goal of providing indexed, comprehensive information on a specific topic within the whole subject area.  As such, it is usually organized with one or more indexes that may be further organized into a hierarchy based on subject taxonomy. The organization of the Reference Documentation User Experience is based on Indexes.

I would like clarification as to whether the documentation is for E-Learning or for Reference.  I think both are lacking.  The "Is this project dead?" thread is a great example of people searching for E-Learning Documentation.  And, the documentation on the Groovy website provides examples that are very helpful, but are also incomplete and certainly not a reference.  The Groovy JDK API Specification is a reference, but in general does not provide any examples to make that reference comprehensible.  That is, a reference work can still have detailed examples.

When Groovy has both E-Learning Documentation and improved Reference Documentation, I think Groovy will get a lot more attention and will grow significantly in popularity.

Best regards,
Steve Amerige, Senior Software Developer
SAS Institute



On 2/8/2013 8:31 AM, Guillaume Laforge 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


Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge
Administrator
Hi Steve,

The distinction between reference documentation and learning documentation is spot on, Steve.

As I explained at the beginning of this thread, we have quite a big goal here, as we really want to revamp the whole documentation, from our web presence with a new skin, our reference doc (language specification, various API guides), also our GroovyDoc (the tool itself and its generated output). 

For the learning experience, we'll also have to write tutorials, I'm happy to hear your thoughts on how to best approach this part of the documentation. I was thinking that the reference documentation and API guides could be didactical enough, also (hopefully) with on-spot runnable examples users can play with. But all ideas are welcome.

Guillaume


On Mon, Apr 22, 2013 at 5:53 PM, Steve Amerige <[hidden email]> wrote:
I'm very glad to hear that documentation might become a priority.  I think it is important to note that there are at least two kinds of documentation:

1. E-Learning Documentation
2. Reference Documentation

E-Learning Documentation has the goal of providing progressive training on a whole subject area.  As such, it is usually organized as a sequence of lessons in which concepts are introduced first, and then built upon.  In addition, as the goal is training, examples and best practices are included.  The organization of the E-Learning Documentation User Experience is based on Concept and Usefulness ordering.

Reference Documentation has the goal of providing indexed, comprehensive information on a specific topic within the whole subject area.  As such, it is usually organized with one or more indexes that may be further organized into a hierarchy based on subject taxonomy. The organization of the Reference Documentation User Experience is based on Indexes.

I would like clarification as to whether the documentation is for E-Learning or for Reference.  I think both are lacking.  The "Is this project dead?" thread is a great example of people searching for E-Learning Documentation.  And, the documentation on the Groovy website provides examples that are very helpful, but are also incomplete and certainly not a reference.  The Groovy JDK API Specification is a reference, but in general does not provide any examples to make that reference comprehensible.  That is, a reference work can still have detailed examples.

When Groovy has both E-Learning Documentation and improved Reference Documentation, I think Groovy will get a lot more attention and will grow significantly in popularity.

Best regards,
Steve Amerige, Senior Software Developer
SAS Institute



On 2/8/2013 8:31 AM, Guillaume Laforge 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





--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

Reply | Threaded
Open this post in threaded view
|

AW: [groovy-user] [ANN] Documentation effort and site redesign

Jochen Eddelbüttel

Hi Guillaume,

 

Just for comparison I’ve just been checking the current state of affairs on jQuery.com. Their reference documentation is fantastic now, but I couldn’t find any tutorial. So without having read “jQuery in Action”, newbies are probably at a complete loss. Having a good tutorial is very important.

 

I’ll continue with my effort to come up with an outline of such a tutorial. What I realized is that the tutorial can leave out some of the Java background at the beginning, but the deep integration with JVM, JDK and Java does require a solid explanation of Java concepts to get across what Groovy is doing for a lot of the more advanced stuff. If Groovy is to become attractive to Python, VB, JavaScript, PHP programmers and the likes, we’ll need to include insight into the parts of Java that are relevant for the Groovy-verse.

 

Take the Groovy bean approach to properties for example or static typing/compilation. Or Groovy’s reliance on java.io, which is covered in a particularly pathetic piece of documentation in the current state.

 

I think a decision needs to be made NOT to assume that the entire audience will already have or acquire elsewhere their Java background. There is no need to cover the JDK in its entirety, but parts that integrate deeply with Groovy and got their share of Grooviness (very much and laudably so in the case of java.io), need to be covered. This will need to include core methods from the JDK itself. As far as I know Collection.contains() is not reinvented in Groovy and frequently used. Documenting List.push() and List.pop() is silly, if there is no reference to List.add() and List.remove() in the first place.

 

At least for the major abstract classes and interfaces that the Groovy JDK expands upon, an inclusion of the original methods is very important. This would at least include:

·        Collection

·        List

·        Map

·        InputStream / OutputStream

·        Reader / Writer

·        File

·        URL

 

An audience that would usually be exposed to java.util.ArrayList by writing def list = [] also should not have to be aware of the complex Java hierarchy of interfaces and superclasses that ArrayList is derived from. If any of these methods are useful in a Groovy context, we should include them. If we feel that getAt(IntRange) makes subList(int fromIndex, int toIndex) obsolete in the Groovy world, we can leave it out. So blindly joining API-docs is not going to do the job. While this may prove tricky for the automated doc tools, we should heed this when writing tutorial sections like “Groovy Collections – In Depth”.

 

Good night for now.

 

Jochen (eddel+)

 

Von: Guillaume Laforge [mailto:glaforge@gmail.com]
Gesendet: Montag, 22. April 2013 21:02
An: Steve Amerige
Cc: Groovy User
Betreff: Re: [groovy-user] [ANN] Documentation effort and site redesign

 

Hi Steve,

 

The distinction between reference documentation and learning documentation is spot on, Steve.

 

As I explained at the beginning of this thread, we have quite a big goal here, as we really want to revamp the whole documentation, from our web presence with a new skin, our reference doc (language specification, various API guides), also our GroovyDoc (the tool itself and its generated output). 

 

For the learning experience, we'll also have to write tutorials, I'm happy to hear your thoughts on how to best approach this part of the documentation. I was thinking that the reference documentation and API guides could be didactical enough, also (hopefully) with on-spot runnable examples users can play with. But all ideas are welcome.

 

Guillaume

 

On Mon, Apr 22, 2013 at 5:53 PM, Steve Amerige <[hidden email]> wrote:

I'm very glad to hear that documentation might become a priority.  I think it is important to note that there are at least two kinds of documentation:

1. E-Learning Documentation
2. Reference Documentation

E-Learning Documentation has the goal of providing progressive training on a whole subject area.  As such, it is usually organized as a sequence of lessons in which concepts are introduced first, and then built upon.  In addition, as the goal is training, examples and best practices are included.  The organization of the E-Learning Documentation User Experience is based on Concept and Usefulness ordering.

Reference Documentation has the goal of providing indexed, comprehensive information on a specific topic within the whole subject area.  As such, it is usually organized with one or more indexes that may be further organized into a hierarchy based on subject taxonomy. The organization of the Reference Documentation User Experience is based on Indexes.

I would like clarification as to whether the documentation is for E-Learning or for Reference.  I think both are lacking.  The "Is this project dead?" thread is a great example of people searching for E-Learning Documentation.  And, the documentation on the Groovy website provides examples that are very helpful, but are also incomplete and certainly not a reference.  The Groovy JDK API Specification is a reference, but in general does not provide any examples to make that reference comprehensible.  That is, a reference work can still have detailed examples.

When Groovy has both E-Learning Documentation and improved Reference Documentation, I think Groovy will get a lot more attention and will grow significantly in popularity.

Best regards,
Steve Amerige, Senior Software Developer
SAS Institute



On 2/8/2013 8:31 AM, Guillaume Laforge 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

 

 



 

--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

 

Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

uris77
Jochen,

I agree to some degree. Java interop should have its separate tutorial. It should be easy to find. I'm going by how I learned Groovy and how I'm learning Clojure & Scala. I was a Java dev, so I already had an advantage, but even so, when I need to interop with Java, I wouldn't want to skim through the introductory documentation. I like how the Clojure books are organized. Java interop have their own chapters, and they focus primarily on the language. I would like to see Groovy take that approach. Focus on Groovy as a language on its own right. Yes, we need to know how to interop with Java, but those are more advanced topics, both for newcomers and existing Java devs and merits a space of its own. Just my 2 cents.


On Tue, Apr 23, 2013 at 4:23 PM, Jochen Eddelbüttel <[hidden email]> wrote:

Hi Guillaume,

 

Just for comparison I’ve just been checking the current state of affairs on jQuery.com. Their reference documentation is fantastic now, but I couldn’t find any tutorial. So without having read “jQuery in Action”, newbies are probably at a complete loss. Having a good tutorial is very important.

 

I’ll continue with my effort to come up with an outline of such a tutorial. What I realized is that the tutorial can leave out some of the Java background at the beginning, but the deep integration with JVM, JDK and Java does require a solid explanation of Java concepts to get across what Groovy is doing for a lot of the more advanced stuff. If Groovy is to become attractive to Python, VB, JavaScript, PHP programmers and the likes, we’ll need to include insight into the parts of Java that are relevant for the Groovy-verse.

 

Take the Groovy bean approach to properties for example or static typing/compilation. Or Groovy’s reliance on java.io, which is covered in a particularly pathetic piece of documentation in the current state.

 

I think a decision needs to be made NOT to assume that the entire audience will already have or acquire elsewhere their Java background. There is no need to cover the JDK in its entirety, but parts that integrate deeply with Groovy and got their share of Grooviness (very much and laudably so in the case of java.io), need to be covered. This will need to include core methods from the JDK itself. As far as I know Collection.contains() is not reinvented in Groovy and frequently used. Documenting List.push() and List.pop() is silly, if there is no reference to List.add() and List.remove() in the first place.

 

At least for the major abstract classes and interfaces that the Groovy JDK expands upon, an inclusion of the original methods is very important. This would at least include:

·        Collection

·        List

·        Map

·        InputStream / OutputStream

·        Reader / Writer

·        File

·        URL

 

An audience that would usually be exposed to java.util.ArrayList by writing def list = [] also should not have to be aware of the complex Java hierarchy of interfaces and superclasses that ArrayList is derived from. If any of these methods are useful in a Groovy context, we should include them. If we feel that getAt(IntRange) makes subList(int fromIndex, int toIndex) obsolete in the Groovy world, we can leave it out. So blindly joining API-docs is not going to do the job. While this may prove tricky for the automated doc tools, we should heed this when writing tutorial sections like “Groovy Collections – In Depth”.

 

Good night for now.

 

Jochen (eddel+)

 

Von: Guillaume Laforge [mailto:[hidden email].com]
Gesendet: Montag, 22. April 2013 21:02
An: Steve Amerige
Cc: Groovy User
Betreff: Re: [groovy-user] [ANN] Documentation effort and site redesign

 

Hi Steve,

 

The distinction between reference documentation and learning documentation is spot on, Steve.

 

As I explained at the beginning of this thread, we have quite a big goal here, as we really want to revamp the whole documentation, from our web presence with a new skin, our reference doc (language specification, various API guides), also our GroovyDoc (the tool itself and its generated output). 

 

For the learning experience, we'll also have to write tutorials, I'm happy to hear your thoughts on how to best approach this part of the documentation. I was thinking that the reference documentation and API guides could be didactical enough, also (hopefully) with on-spot runnable examples users can play with. But all ideas are welcome.

 

Guillaume

 

On Mon, Apr 22, 2013 at 5:53 PM, Steve Amerige <[hidden email]> wrote:

I'm very glad to hear that documentation might become a priority.  I think it is important to note that there are at least two kinds of documentation:

1. E-Learning Documentation
2. Reference Documentation

E-Learning Documentation has the goal of providing progressive training on a whole subject area.  As such, it is usually organized as a sequence of lessons in which concepts are introduced first, and then built upon.  In addition, as the goal is training, examples and best practices are included.  The organization of the E-Learning Documentation User Experience is based on Concept and Usefulness ordering.

Reference Documentation has the goal of providing indexed, comprehensive information on a specific topic within the whole subject area.  As such, it is usually organized with one or more indexes that may be further organized into a hierarchy based on subject taxonomy. The organization of the Reference Documentation User Experience is based on Indexes.

I would like clarification as to whether the documentation is for E-Learning or for Reference.  I think both are lacking.  The "Is this project dead?" thread is a great example of people searching for E-Learning Documentation.  And, the documentation on the Groovy website provides examples that are very helpful, but are also incomplete and certainly not a reference.  The Groovy JDK API Specification is a reference, but in general does not provide any examples to make that reference comprehensible.  That is, a reference work can still have detailed examples.

When Groovy has both E-Learning Documentation and improved Reference Documentation, I think Groovy will get a lot more attention and will grow significantly in popularity.

Best regards,
Steve Amerige, Senior Software Developer
SAS Institute



On 2/8/2013 8:31 AM, Guillaume Laforge 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

 

 



 

--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

 




--
Color me impractical but I’d rather be able to look at myself in the mirror than be rich.
-Evan Light
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Jochen Eddelbüttel
Robert,
 
I don't think we are too far apart here. There need to be focussed chapters introducing specific areas of Groovy usage and to some extent that is already the case in the current documentation, e.g. for embedding Groovy. Creating a dedicated section in the documentation explaining interoperability with Java is acutally a very good idea.
 
I just want to make sure that things that come in from the Java side are explicitly mentioned and not taken for granted wherever any part of the documentation relies on them. I think it is worthwhile to point out what Set is good for, even though it doesn't sport specific Groovy syntax like List and Map and to have this in a tutorial chapter about collections in Groovy. The tutorial part of the documentation should establish a common ground, so that any specialist chapters can be studied in whatever order the reader wants to.
 
Or take javax.mail for example. With no separate Groovy mail library, there should be some rock solid examples (in Groovy) showing how mail is sent and received and IMAP folders are accessed. I bet that JRuby can utlize net/smtp ported form the Ruby standard library. With Groovy's focus on not reinventing the wheel where it's already invented, we should at least point out where the the trunk lever is in our car.
 
Jochen
 
Roberto Guerra <[hidden email]> hat am 24. April 2013 um 00:30 geschrieben:

Jochen,

I agree to some degree. Java interop should have its separate tutorial. It should be easy to find. I'm going by how I learned Groovy and how I'm learning Clojure & Scala. I was a Java dev, so I already had an advantage, but even so, when I need to interop with Java, I wouldn't want to skim through the introductory documentation. I like how the Clojure books are organized. Java interop have their own chapters, and they focus primarily on the language. I would like to see Groovy take that approach. Focus on Groovy as a language on its own right. Yes, we need to know how to interop with Java, but those are more advanced topics, both for newcomers and existing Java devs and merits a space of its own. Just my 2 cents.
 
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Jochen Eddelbüttel
I meant: NOT too far apart.
"[hidden email]" <[hidden email]> hat am 24. April 2013 um 14:37 geschrieben:

Robert,
 
I don't think we are too far apart here. There need to be focussed chapters introducing specific areas of Groovy usage and to some extent that is already the case in the current documentation, e.g. for embedding Groovy. Creating a dedicated section in the documentation explaining interoperability with Java is acutally a very good idea.
 
I just want to make sure that things that come in from the Java side are explicitly mentioned and not taken for granted wherever any part of the documentation relies on them. I think it is worthwhile to point out what Set is good for, even though it doesn't sport specific Groovy syntax like List and Map and to have this in a tutorial chapter about collections in Groovy. The tutorial part of the documentation should establish a common ground, so that any specialist chapters can be studied in whatever order the reader wants to.
 
Or take javax.mail for example. With no separate Groovy mail library, there should be some rock solid examples (in Groovy) showing how mail is sent and received and IMAP folders are accessed. I bet that JRuby can utlize net/smtp ported form the Ruby standard library. With Groovy's focus on not reinventing the wheel where it's already invented, we should at least point out where the the trunk lever is in our car.
 
Jochen
 
Roberto Guerra <[hidden email]> hat am 24. April 2013 um 00:30 geschrieben:

Jochen,

I agree to some degree. Java interop should have its separate tutorial. It should be easy to find. I'm going by how I learned Groovy and how I'm learning Clojure & Scala. I was a Java dev, so I already had an advantage, but even so, when I need to interop with Java, I wouldn't want to skim through the introductory documentation. I like how the Clojure books are organized. Java interop have their own chapters, and they focus primarily on the language. I would like to see Groovy take that approach. Focus on Groovy as a language on its own right. Yes, we need to know how to interop with Java, but those are more advanced topics, both for newcomers and existing Java devs and merits a space of its own. Just my 2 cents.
 

 
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

uris77
Jochen,

Yeah, I agree with your points. I was also thinking about something like 'Groovy for Java Developers' and 'Java for Groovy Developers'. Maybe there could be links from the basics to the advanced sections, like you mentioned. It is quite a big project.


On Wed, Apr 24, 2013 at 6:57 AM, [hidden email] <[hidden email]> wrote:
I meant: NOT too far apart.
"[hidden email]" <[hidden email]> hat am 24. April 2013 um 14:37 geschrieben:

Robert,
 
I don't think we are too far apart here. There need to be focussed chapters introducing specific areas of Groovy usage and to some extent that is already the case in the current documentation, e.g. for embedding Groovy. Creating a dedicated section in the documentation explaining interoperability with Java is acutally a very good idea.
 
I just want to make sure that things that come in from the Java side are explicitly mentioned and not taken for granted wherever any part of the documentation relies on them. I think it is worthwhile to point out what Set is good for, even though it doesn't sport specific Groovy syntax like List and Map and to have this in a tutorial chapter about collections in Groovy. The tutorial part of the documentation should establish a common ground, so that any specialist chapters can be studied in whatever order the reader wants to.
 
Or take javax.mail for example. With no separate Groovy mail library, there should be some rock solid examples (in Groovy) showing how mail is sent and received and IMAP folders are accessed. I bet that JRuby can utlize net/smtp ported form the Ruby standard library. With Groovy's focus on not reinventing the wheel where it's already invented, we should at least point out where the the trunk lever is in our car.
 
Jochen
 
Roberto Guerra <[hidden email]> hat am 24. April 2013 um 00:30 geschrieben:

Jochen,

I agree to some degree. Java interop should have its separate tutorial. It should be easy to find. I'm going by how I learned Groovy and how I'm learning Clojure & Scala. I was a Java dev, so I already had an advantage, but even so, when I need to interop with Java, I wouldn't want to skim through the introductory documentation. I like how the Clojure books are organized. Java interop have their own chapters, and they focus primarily on the language. I would like to see Groovy take that approach. Focus on Groovy as a language on its own right. Yes, we need to know how to interop with Java, but those are more advanced topics, both for newcomers and existing Java devs and merits a space of its own. Just my 2 cents.
 

 



--
Color me impractical but I’d rather be able to look at myself in the mirror than be rich.
-Evan Light
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] Documentation effort and site redesign

Andre Steingress
Hi,

The documentation should clearly mention Java knowledge is needed and should rely on it for the most parts IMHO. We shouldn't try to write the documentation under the assumption the reader is lacking (basic) Java knowledge.

I am afraid writing under this assumption could open doors to make the documentation hard to maintain (Groovy supports JDK 5/6/7,8 on the horizon) and even more confusing for non-Java devs as the Groovy documentation can't capture the "whole picture".

Groovy's agreed upon goal is to extend Java and not to replace it. As a matter of fact, Groovy is way more integrated with the JDK APIs and Java as it is the case for Clojure or Scala (default Java package imports, basic data types, collection types, generics, annotations, JDK API extension methods, JavaBeans, JavaDoc documentation vs. GroovyDoc documentation etc.). It might not be a selling point for programmers without Java knowledge, but in practice it means developers interested in Groovy have to get in touch with Java and its APIs to become productive. And that's just natural as Groovy extends Java and its APIs.

This is not a lame excuse to decrease the documentation effort and I am not saying we shouldn't provide tutorials or hints in the documentation for people without Java knowledge, I just wanted to point out that there is nothing bad with assuming JDK/Java knowledge for a language so heavily mixed with Java. We should primarily concentrate on the documentation of the Groovy programming language. 

Cheers, André

==========================
Andre Steingress

https://twitter.com/asteingr
https://github.com/andresteingress

Am 24.04.2013 um 15:26 schrieb Roberto Guerra <[hidden email]>

Jochen,

Yeah, I agree with your points. I was also thinking about something like 'Groovy for Java Developers' and 'Java for Groovy Developers'. Maybe there could be links from the basics to the advanced sections, like you mentioned. It is quite a big project.


On Wed, Apr 24, 2013 at 6:57 AM, [hidden email] <[hidden email]> wrote:
I meant: NOT too far apart.
"[hidden email]" <[hidden email]> hat am 24. April 2013 um 14:37 geschrieben:

Robert,
 
I don't think we are too far apart here. There need to be focussed chapters introducing specific areas of Groovy usage and to some extent that is already the case in the current documentation, e.g. for embedding Groovy. Creating a dedicated section in the documentation explaining interoperability with Java is acutally a very good idea.
 
I just want to make sure that things that come in from the Java side are explicitly mentioned and not taken for granted wherever any part of the documentation relies on them. I think it is worthwhile to point out what Set is good for, even though it doesn't sport specific Groovy syntax like List and Map and to have this in a tutorial chapter about collections in Groovy. The tutorial part of the documentation should establish a common ground, so that any specialist chapters can be studied in whatever order the reader wants to.
 
Or take javax.mail for example. With no separate Groovy mail library, there should be some rock solid examples (in Groovy) showing how mail is sent and received and IMAP folders are accessed. I bet that JRuby can utlize net/smtp ported form the Ruby standard library. With Groovy's focus on not reinventing the wheel where it's already invented, we should at least point out where the the trunk lever is in our car.
 
Jochen
 
Roberto Guerra <[hidden email]> hat am 24. April 2013 um 00:30 geschrieben:

Jochen,

I agree to some degree. Java interop should have its separate tutorial. It should be easy to find. I'm going by how I learned Groovy and how I'm learning Clojure & Scala. I was a Java dev, so I already had an advantage, but even so, when I need to interop with Java, I wouldn't want to skim through the introductory documentation. I like how the Clojure books are organized. Java interop have their own chapters, and they focus primarily on the language. I would like to see Groovy take that approach. Focus on Groovy as a language on its own right. Yes, we need to know how to interop with Java, but those are more advanced topics, both for newcomers and existing Java devs and merits a space of its own. Just my 2 cents.
 

 



--
Color me impractical but I’d rather be able to look at myself in the mirror than be rich.
-Evan Light

Reply | Threaded
Open this post in threaded view
|

AW: [groovy-user] [ANN] Documentation effort and site redesign

Jochen Eddelbüttel
In reply to this post by uris77

Here is part two of my hypothetical outline for a Groovy tutorial that does not set „Learn Java first“ as a prerequisite:

 

https://github.com/eddelplus/DEGroovyTut/blob/master/asciidoc/intermediate.adoc

 

Some of the chapters map pretty well to parts of  the existing documentation.

 

The core of the exercise is finding the right order in which the tutorial can get stuff across. Builders could be introduced ‘as is’, without much prior detail about closures and meta-programming. But if those chapters come before the builders and slurpers, they’ll so much more comprehensible.

 

Let me know what you think. The two outlines are as far as I can go on my own. There are a couple of chapters that I can image myself writing, but I’d like to base that on examples from others as well.

 

Cheers,

 

Jochen (eddel+)

 

 

Von: Roberto Guerra [mailto:[hidden email]]
Gesendet: Mittwoch, 24. April 2013 00:30
An: [hidden email]
Betreff: Re: [groovy-user] [ANN] Documentation effort and site redesign

 

Jochen,

I agree to some degree. Java interop should have its separate tutorial. It should be easy to find. I'm going by how I learned Groovy and how I'm learning Clojure & Scala. I was a Java dev, so I already had an advantage, but even so, when I need to interop with Java, I wouldn't want to skim through the introductory documentation. I like how the Clojure books are organized. Java interop have their own chapters, and they focus primarily on the language. I would like to see Groovy take that approach. Focus on Groovy as a language on its own right. Yes, we need to know how to interop with Java, but those are more advanced topics, both for newcomers and existing Java devs and merits a space of its own. Just my 2 cents.

 

On Tue, Apr 23, 2013 at 4:23 PM, Jochen Eddelbüttel <[hidden email]> wrote:

Hi Guillaume,

 

Just for comparison I’ve just been checking the current state of affairs on jQuery.com. Their reference documentation is fantastic now, but I couldn’t find any tutorial. So without having read “jQuery in Action”, newbies are probably at a complete loss. Having a good tutorial is very important.

 

I’ll continue with my effort to come up with an outline of such a tutorial. What I realized is that the tutorial can leave out some of the Java background at the beginning, but the deep integration with JVM, JDK and Java does require a solid explanation of Java concepts to get across what Groovy is doing for a lot of the more advanced stuff. If Groovy is to become attractive to Python, VB, JavaScript, PHP programmers and the likes, we’ll need to include insight into the parts of Java that are relevant for the Groovy-verse.

 

Take the Groovy bean approach to properties for example or static typing/compilation. Or Groovy’s reliance on java.io, which is covered in a particularly pathetic piece of documentation in the current state.

 

I think a decision needs to be made NOT to assume that the entire audience will already have or acquire elsewhere their Java background. There is no need to cover the JDK in its entirety, but parts that integrate deeply with Groovy and got their share of Grooviness (very much and laudably so in the case of java.io), need to be covered. This will need to include core methods from the JDK itself. As far as I know Collection.contains() is not reinvented in Groovy and frequently used. Documenting List.push() and List.pop() is silly, if there is no reference to List.add() and List.remove() in the first place.

 

At least for the major abstract classes and interfaces that the Groovy JDK expands upon, an inclusion of the original methods is very important. This would at least include:

·        Collection

·        List

·        Map

·        InputStream / OutputStream

·        Reader / Writer

·        File

·        URL

 

An audience that would usually be exposed to java.util.ArrayList by writing def list = [] also should not have to be aware of the complex Java hierarchy of interfaces and superclasses that ArrayList is derived from. If any of these methods are useful in a Groovy context, we should include them. If we feel that getAt(IntRange) makes subList(int fromIndex, int toIndex) obsolete in the Groovy world, we can leave it out. So blindly joining API-docs is not going to do the job. While this may prove tricky for the automated doc tools, we should heed this when writing tutorial sections like “Groovy Collections – In Depth”.

 

Good night for now.

 

Jochen (eddel+)

 

Von: Guillaume Laforge [mailto:[hidden email].com]
Gesendet: Montag, 22. April 2013 21:02
An: Steve Amerige
Cc: Groovy User
Betreff: Re: [groovy-user] [ANN] Documentation effort and site redesign

 

Hi Steve,

 

The distinction between reference documentation and learning documentation is spot on, Steve.

 

As I explained at the beginning of this thread, we have quite a big goal here, as we really want to revamp the whole documentation, from our web presence with a new skin, our reference doc (language specification, various API guides), also our GroovyDoc (the tool itself and its generated output). 

 

For the learning experience, we'll also have to write tutorials, I'm happy to hear your thoughts on how to best approach this part of the documentation. I was thinking that the reference documentation and API guides could be didactical enough, also (hopefully) with on-spot runnable examples users can play with. But all ideas are welcome.

 

Guillaume

 

On Mon, Apr 22, 2013 at 5:53 PM, Steve Amerige <[hidden email]> wrote:

I'm very glad to hear that documentation might become a priority.  I think it is important to note that there are at least two kinds of documentation:

1. E-Learning Documentation
2. Reference Documentation

E-Learning Documentation has the goal of providing progressive training on a whole subject area.  As such, it is usually organized as a sequence of lessons in which concepts are introduced first, and then built upon.  In addition, as the goal is training, examples and best practices are included.  The organization of the E-Learning Documentation User Experience is based on Concept and Usefulness ordering.

Reference Documentation has the goal of providing indexed, comprehensive information on a specific topic within the whole subject area.  As such, it is usually organized with one or more indexes that may be further organized into a hierarchy based on subject taxonomy. The organization of the Reference Documentation User Experience is based on Indexes.

I would like clarification as to whether the documentation is for E-Learning or for Reference.  I think both are lacking.  The "Is this project dead?" thread is a great example of people searching for E-Learning Documentation.  And, the documentation on the Groovy website provides examples that are very helpful, but are also incomplete and certainly not a reference.  The Groovy JDK API Specification is a reference, but in general does not provide any examples to make that reference comprehensible.  That is, a reference work can still have detailed examples.

When Groovy has both E-Learning Documentation and improved Reference Documentation, I think Groovy will get a lot more attention and will grow significantly in popularity.

Best regards,
Steve Amerige, Senior Software Developer
SAS Institute



On 2/8/2013 8:31 AM, Guillaume Laforge 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

 

 



 

--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

 




--

Color me impractical but I’d rather be able to look at myself in the mirror than be rich.
-Evan Light

123456