Quantcast

[ANN] Documentation effort and site redesign

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

Re: [ANN] Documentation effort and site redesign

Cédric Champeau
Correct me if I'm wrong Guillaume, but from what I understand, your first candidate right now is dokspek, which allows you do perform the unit tests on the documentation, with a modification to use markdown syntax.

That's fine for me (although I really dislike markdown syntax for bold or italics, as well as indent for code, ok I don't like markdown :)), but I don't see how dokspek deals with table of contents, or, in general, with links between pages or hierarchical structures.

Le 11/02/2013 17:14, Guillaume Laforge a écrit :

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

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

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

I was kidding for your volunteering with LaTeX ;-)

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

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


-- 
Cédric Champeau
SpringSource - A Division Of VMware
http://www.springsource.com/
http://twitter.com/CedricChampeau
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Guillaume Laforge-4

On Mon, Feb 11, 2013 at 5:22 PM, Cédric Champeau <[hidden email]> wrote:
Correct me if I'm wrong Guillaume, but from what I understand, your first candidate right now is dokspek, which allows you do perform the unit tests on the documentation, with a modification to use markdown syntax.

Yes, that's why I've been creating it :-)
 
That's fine for me (although I really dislike markdown syntax for bold or italics, as well as indent for code, ok I don't like markdown :)),

I'm not particularly in love with Markdown per se, but it's one syntax that is quite widely known and used (Github, Stack Overflow use it), and correctly tooled for authoring (text editors, IDEs, etc).

The Pegdown library (https://github.com/sirthias/pegdown) adds some extensions to the original Markdown, like the ones used on Github and elsewhere.
 
but I don't see how dokspek deals with table of contents, or, in general, with links between pages or hierarchical structures.

It's something to be worked on.
It has an embryonic table of content but it's not really finished or ideal yet.

Guillaume
 

Le 11/02/2013 17:14, Guillaume Laforge a écrit :

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

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

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

I was kidding for your volunteering with LaTeX ;-)

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

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


-- 
Cédric Champeau
SpringSource - A Division Of VMware
http://www.springsource.com/
http://twitter.com/CedricChampeau



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

uris77
I vote for Markdown. It is easy and most people know it already. If you choose something obscure you might not get as many contributors since they have to learn about it first. Then it will take time before we feel comfortable enough with it that we can start writing documentation.

So if something different than Markdown is chosen, it has to be as easy as Markdown or easier for there to be more contributors.


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

On Mon, Feb 11, 2013 at 5:22 PM, Cédric Champeau <[hidden email]> wrote:
Correct me if I'm wrong Guillaume, but from what I understand, your first candidate right now is dokspek, which allows you do perform the unit tests on the documentation, with a modification to use markdown syntax.

Yes, that's why I've been creating it :-)
 
That's fine for me (although I really dislike markdown syntax for bold or italics, as well as indent for code, ok I don't like markdown :)),

I'm not particularly in love with Markdown per se, but it's one syntax that is quite widely known and used (Github, Stack Overflow use it), and correctly tooled for authoring (text editors, IDEs, etc).

The Pegdown library (https://github.com/sirthias/pegdown) adds some extensions to the original Markdown, like the ones used on Github and elsewhere.
 
but I don't see how dokspek deals with table of contents, or, in general, with links between pages or hierarchical structures.

It's something to be worked on.
It has an embryonic table of content but it's not really finished or ideal yet.

Guillaume
 

Le 11/02/2013 17:14, Guillaume Laforge a écrit :

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

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

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

I was kidding for your volunteering with LaTeX ;-)

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

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


-- 
Cédric Champeau
SpringSource - A Division Of VMware
http://www.springsource.com/
http://twitter.com/CedricChampeau



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



--
The Journey Is The Reward.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

tim yates-2
In reply to this post by Guillaume Laforge-4

Not advocating the latex route, but R has sweave to embed R code in the latex docs

A search for a non R sweave lead me to dexy.it which looks interesting from a first glance

On 11 Feb 2013 15:44, "Guillaume Laforge" <[hidden email]> wrote:

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

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

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

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

Guillaume
 

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

Re: [ANN] Documentation effort and site redesign

Daniel Sun
In reply to this post by Guillaume Laforge
Hi Guillaume,

> Our GroovyDoc, in particular, looks like the old JavaDoc format, not very sexy or appealing.
   We can search classes or methods through GroovyHelp, which supports javadoc and groovydoc.

Cheers,
Daniel.Sun

---------------------------------------




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

Re: [ANN] Documentation effort and site redesign

Daniel Sun
In reply to this post by uris77
It seems that you are also looking for some features already offered by GroovyHelp.


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

Re: [ANN] Documentation effort and site redesign

uris77
Yes, but with a web interface. IMO it is better to have this feature in the groovy website itself, than having to download software to my machine to  interact with the docs.


On Sun, Feb 17, 2013 at 10:40 AM, daniel_sun <[hidden email]> wrote:
It seems that you are also looking for some features already offered by
GroovyHelp <http://code.google.com/p/groovyhelp/>  .

<http://groovy.329449.n5.nabble.com/file/n5713101/o_groovyhelp3.2.0_02.png>




--
View this message in context: http://groovy.329449.n5.nabble.com/ANN-Documentation-effort-and-site-redesign-tp5712875p5713101.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





--
The Journey Is The Reward.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Daniel Sun
> Yes, but with a web interface. IMO it is better to have this feature in the groovy website itself, than having to download software to my machine to  interact with the docs.
I see, but the special software for javadoc & groovydoc can offer addition useful functions, such as managing all API docs, comparing APIs. While it's hard for web to achieve.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

ironhammer
This post has NOT been accepted by the mailing list yet.
In reply to this post by Guillaume Laforge
I think this is a great idea!  I have always found the Python documentation to be very well done, I am always able to find exactly what I need with it. Here is an example: http://docs.python.org/3/  This documentation was created using Sphinx - http://sphinx-doc.org/ The same could be used to get the Groovy documentation converted in a timely manner.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ANN] Documentation effort and site redesign

Josef
This post has NOT been accepted by the mailing list yet.
In reply to this post by Guillaume Laforge-4
Regarding the search feature for new site redesign.  One thing that some sites use, especially blogs, is a simple compact tag cloud.  If each document resource is also tagged, the site would create a faster access to most documented and possibly most important topics.

But, tags are not really information.  Tags can be used to create dynamic longer term categories.  I wrote about this in a post titled "From Tags To Categories".

The actual site experience design can draw on many existing sites, like http://dojotoolkit.org/documentation/ where the Dojo version is used to limit the content (note to me that site is hard to use).

-- Josef
 
123456
Loading...