Quantcast

[ANN] Documentation effort and site redesign

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

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

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

 

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

1 ... 3456
Loading...