API manuals for each language

[Tim Fox]

In the current Vert.x 1.x documentation on vertx.io we currently maintain a version of the API manual for each language we support.

In Vert.x 2.0 language support has been decentralised into separate optional modules, and we hope to encourage the community to develop and provide their own language implementations in the form of modules.

Bearing this in mind, and also bearing in mind that maintaining this documentation is quite a lot of work, do you think we should maintain just the core Java API manual on the website and let the users use api documentation (GroovyDoc, pydoc, jsdocs etc) to figure out how to use the apis?

[Norman Maurer]

I agree here… I think we should only have a manual for the java API here.

What we may could do is to generate a manual for different languages from the github wiki and so allow the users to write it and integrate it with the website.

This is what we do in the netty project. 

Bye,

Norman

--
You received this message because you are subscribed to the Google Groups "vert.x" group.
To unsubscribe from this group and stop receiving emails from it, send an email to vertx+un...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Bruno Bonacci]

To be honest, the beauty of  Vert.x really shines with other languages than Java., such as Groovy and JavaScript.

I do understand that maintaining the the documentation is a lot of work, but a good language specific documentation is really important to cut down learning curve and increase the adoption.

Maybe a wiki style doc where you can edit the code snippet online, can be an easier and faster approach.

Also consider how often you are going to change the core APIs once the major version is out?

Bruno 

[bytor99999]

I agree with Bruno. I am a Java guy, but for Vert.x development, I don't really ever want to use Java for it. I just find that code uglier than say in Groovy or Javascript.

There was an issue in 1.3.x where the apis between Java and Groovy were different, mostly because of an oversight, but one where without the separate documentation I would have never figured out.

Thanks

Mark

[Joern Bernhardt]

a) +1 for having a Wiki-style documentation for the handbooks would be great.
b) Please continue to support language modules as "official" modules. Knowing that there are people who will accept pull requests and support the language I chose, is really something we don't want to miss if you decide to let users handle the languages by themselves...

Thanks
Joern

[Bruno Bonacci]

Another alternative, probably easier to manage is to create the whole documentation like the vertx home page example.

Most of the documentation will be the same across all languages, what change is the code snippet as sample.

So my suggestion is to create only one set of doc across all languages and where a code snippet appear put a tabbed view (like the home page) for each language.

Those code snippet might be also gists hosted on github or some other sort of wiki that can be changed.

This solution should make the life easier for the project team as there is only one set of docs, but still keeping the language based examples.

What's your thoughts on this guys?

Bruno