[Hawkular-dev] Documentation writing

[Heiko W.Rupp]

> Am 19.02.2015 um 21:50 schrieb Catherine Robson <crobson at redhat.com>:
> 
> 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

Actually this poll is about community web site - user and developer documentation.

> - Bring documentation into the web console as context sensitive help pop-ups/sidebars

Yes, that can be done in at least two ways:
- reference the AsciiDoc content and render it locally into e.g. html
- have the community site be rendered into html and reference and just display it locally

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

Asciidoc is first and foremost a markup schema that is very human readable without additional processing tools.

For example this is a part of the rest-api documentation (generated from Swagger+Jax-RS annotations on the code)

-----------------------------snip--------------------------
= Rest-Api for Hawkular-Inventory

== Rest api for Hawkular Inventory

Implemented in: org.hawkular.inventory.rest.RestApi

Produces:

* application/json

=== GET //

[.lead]
Description: Just returns a string to verify reachability

Return type: org.hawkular.inventory.rest.StringWrapper


=== POST //{tenantId}/resources

[.lead]
Description: Add a new resource for the passed tenantId

Return type: javax.ws.rs.core.Response

.Parameters
|===
|Name|Required|Type|Allowed Values|Default Value|Description

|tenantId|true|PATH|all||Id of the tenant
||true|BODY|all||The Resource to add
|===

-----------------------------snip--------------------------

And like in html, anchors can be built in and referenced later.

For e.g. http://hawkular.github.io/community/join.html
the source code is here: https://raw.githubusercontent.com/hawkular/hawkular.github.io/pages/src/main/jbake/content/community/join.adoc

Hope that helps

    Heiko


> 



> - Catherine
> 
> 
>> 	Heiko W.Rupp	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	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
> 

-- 
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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/hawkular-dev/attachments/20150219/4e552384/attachment.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/4e552384/attachment.jpg