You have me as a proofreading volunteer. I am very much in the no-Java-prerequisite camp.
Schalk W. Cronjé
[Sent from mobile phone]
-------- Original message --------
From: Jochen Eddelbüttel <[hidden email]>
Date: 25/04/2013 22:01 (GMT+00:00)
To: [hidden email]
Subject: AW: [groovy-user] [ANN] Documentation effort and site redesign
Here is part two of my hypothetical outline for a Groovy tutorial that does not set „Learn Java first“ as a prerequisite:
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.
On Tue, Apr 23, 2013 at 4:23 PM, Jochen Eddelbüttel <[hidden email]> wrote:
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.
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:
· InputStream / OutputStream
· Reader / Writer
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.
Von: Guillaume Laforge [mailto:[hidden email].com]
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.
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:
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.
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!
Color me impractical but I’d rather be able to look at myself in the mirror than be rich.
|Free forum by Nabble||Edit this page|