[Hawkular-dev] Documentation writing

[Heiko W.Rupp]

Hey,

as we made some progress with hawkular.github.io, the question came up what should go there and if we can't just use something else instead.

I am very much in favor of using AsciiDoc + git for the documentation -- user and developer

Clear advantages that I see for this solution:

- versioning is easy as it is built into git. We can easily create branches for various versions of the Hawkular
without the complicated clone process that we had in the past
- offline possibility an author does not need to be online to write docs
- AsciiDoc is plain text. The pages may have a handful of specific header lines, but if you don't want to format any markup, then just don't
- Contributing is easy. People just git clone the repo, make their changes and submit a pull-request
- docs are directly rendered on GitHub
- AsciiDoc is already used in our README.adoc files
- With AsciiDoctor there is a good tool chain for creating good print, html, pdf, docbook output
- it is possible to write docs in vi/emacs/Notepad

Tooling may not yet be that perfect; the mvn jbake:inline mode is already quite well able to re-create 
the website locally though; with a browser extension like "live-reload", editing a text is as wysiwyg as on a wiki


There are other JBoss projects that follow the AsciiDoc+git approach with great success
like http://arquillian.org, http://hibernate.org, http://liveoak.io, http://torquebox.org(*)

Anyway I've started a doodle to get feedback and then proceed further - so please visit
http://doodle.com/a8ctk6wgwi3nh9f8
so that we can come to a documentation solution that we all use.

  Heiko

*) Actually uses Markdown as markup language