About documentation

[Antoine Sabot-Durand]

Hi All,

I opened a ticket about documentation 

https://issues.jboss.org/browse/AGOVA-4

After looking around and asking to people working on Java OSS framework, it seems that Asciidoc is one of the best solution :

http://www.methods.co.nz/asciidoc/

Your input would be appreciated. Here or on the Jira ticket.

regards

Antoine SABOT-DURAND
---------------------------------------
Blog : http://www.next-presso.fr
Twitter ; http://twitter.com/antoine_sd
LinkedIn : http://fr.linkedin.com/in/antoinesabotdurand
06 08 55 34 26

[Paul Dijou]

Hi,

I have make some research in the same purpose in order to write some doc about RichFaces CDK and I've come to the conclusion to use AsciiDoc. I should be able to provide real feedback about that tool in July (I'm a bit busy in June).

Following a mail from Jason Porter on the DeltaSpike mailing list about documentation :

* Apache CMS -- AIUI, this is a perl script that runs some extra stuff.
More info and history is available at http://www.apache.org/dev/cms. Not
sure if you have to be using SVN to get the rebuild on checkin support or
not.

* DocBook -- I think we're all familiar with DocBook.

* Sphinx or plain ReStructuredText -- A wiki markup. Somewhat difficult to
use and remember, heavily used in the Python community

* Markdown -- We all know what that is. It has native support in
apache-cms. Great for simple stuff, starts breaking down quickly when used
for technical documentation

* asciidoc -- Another wiki markup.http://www.methods.co.nz/asciidoc/. Easy
to use, very similar to markdown, more expressive, very similar feature set
to docbook.

Earlier in this thread we wanted to have the ability to have buildable docs
by maven. However, if there isn't a plugin already available, which to my
knowledge would take out everything but docbook and sphinx, possibly
markdown, we'd have to build one. We also want it easy for contributors to
use, which is a downside to docbook and sphinx. If anyone has any others
they'd like to put into the match, please speak up.

2012/6/3 Antoine Sabot-Durand <ant...@sabot-durand.net>

[Werner Keil]

As it happens, we're just having the same discussion on what documentation markup to use for those documents leaving the intranet, having to go to external parties like clients or integrators:

http://en.wikipedia.org/wiki/Lightweight_markup_language

Except that it's written in Python (not a problem here, we code more Python than Java for most of our work;-) there seems nothing wrong with AsciiDoc. I assume, if some Apache projects including DeltaSpike may use it, there's also an easy way of integrating it with Maven.

For most of the Unit-API documentation and entire site we used Maven's own APT markup. Which should be quite popular with several Apache projects, but outside of Maven's lifecycle didn't seem to have gained much momentum.

So using something more widely accepted seems fair.

Werner