Quantcast

[ANN] Documentation effort and site redesign

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
51 messages Options
1234 ... 6
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

[ANN] Documentation effort and site redesign

Guillaume Laforge
Administrator
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
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

uris77
This post has NOT been accepted by the mailing list yet.
Re the search feature similar to http://www.scala-lang.org/api/current/index.html#package, we can go a little further and do something similar to github. If you press t and start typing, github will do a live search for files that match that name. Don't know how that would fit inside an api documentation.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

hindsholm
In reply to this post by Guillaume Laforge
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!

But of course: the fact that the documentation is inadequate doesn't mean that Groovy is!


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


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
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





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

Re: [ANN] Documentation effort and site redesign

hindsholm

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





--
Guillaume Laforge
Groovy Project Manager
Head of Groovy Development at SpringSource
http://www.springsource.com/g2one

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4
Thanks!


On Fri, Feb 8, 2013 at 3:31 PM, Morten Hindsholm <[hidden email]> wrote:

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





--
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

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


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Scott Hickey-2
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


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Russel Winder-3
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.

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.

--
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
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

chiquitinxx
In reply to this post by Scott Hickey-2
Hello!

I miss a good screencast, at main page, showing the Groovy power in 5 - 10 mins.
Awesome sites for beginners as Code School tryruby.org
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 :)

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


1234 ... 6
Loading...