[Hawkular-dev] Documentation writing

[Thomas Heute]

I added an article about the docs we intend to produce, how and where to 
publish:
https://developer.jboss.org/wiki/HawkularDocumentations

Feel free to comment

(Yes it's another source of documentation ;))

Thomas


On 02/19/2015 10:00 PM, Heiko W.Rupp wrote:
>
>> Am 19.02.2015 um 21:50 schrieb Catherine Robson <crobson at redhat.com
>> <mailto: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.RuppFebruary 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.RuppFebruary 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
>
>
>
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>