[Hawkular-dev] Documentation writing

[Heiko W.Rupp]

Hey,

please add yourself to the Doodle at http://doodle.com/a8ctk6wgwi3nh9f8 
I will close that tomorrow SOB

 Heiko


> Am 17.02.2015 um 15:15 schrieb Heiko W.Rupp <hrupp at redhat.com>:
> 
> 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
> 
> 
> 
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev

-- 
Reg. Adresse: Red Hat GmbH, Technopark II, Haus C, 
Werner-von-Siemens-Ring 14, D-85630 Grasbrunn
Handelsregister: Amtsgericht München HRB 153243
Geschäftsführer: Charles Cachera, Michael Cunningham, Paul Hickey, Charlie Peters