Re: [Hawkular-dev] Documentation writing

Actually this poll is about community web site - user and developer documentation. 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 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/m... 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(a)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