[Hawkular-dev] Documentation writing

[Catherine Robson]

Would we be able to take documentation written in Git with Asciidoc and 
dynamically place that into other UI outputs?  Two reasons of why this 
might be useful:

- Bring documentation into the Hawkular community website to describe 
certain capabilties
- Bring documentation into the web console as context sensitive help 
pop-ups/sidebars

My current understanding of Asciidoc tells me this would be possible - 
but wanted to ask!

- Catherine


> Heiko W.Rupp <mailto:hrupp at redhat.com>
> February 19, 2015 at 4:51 AM
> Hey,
>
> please add yourself to the Doodle at http://doodle.com/a8ctk6wgwi3nh9f8
> I will close that tomorrow SOB
>
> Heiko
>
>
>
> Heiko W.Rupp <mailto:hrupp at redhat.com>
> February 17, 2015 at 9:15 AM
> 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

-- 
Catherine Robson
User Experience Design
Red Hat JBoss Middleware
c: 978-944-3825

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/hawkular-dev/attachments/20150219/c78e3613/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: compose-unknown-contact.jpg
Type: image/jpeg
Size: 770 bytes
Desc: not available
Url : http://lists.jboss.org/pipermail/hawkular-dev/attachments/20150219/c78e3613/attachment-0001.jpg