Documentation

[theute]

Any preference for RHQ Metrics documentation (Writing and publishing) ?

1. Sub-space of Home - RHQ - Project Documentation Editor ?
2. Using GitBook https://www.gitbook.io/ like Fabric8 https://github.com/fabric8io/fabric8/tree/master/docs -> Introduction | Fabric8 Documentation
   1. Docs within the project (versionned with the project)
   2. Docs as a separate project
3. AsciiDoc ? (How/Where to publish)

I have a personal preference to start with 2.1 but I won't be the person dealing with it on a daily basis.

[jastrachan]

I don't mind personally. FWIW we went with gitbook / markdown on fabric8 just as thats what we started with. (Though I do really like gitbook's HTML!).

I guess asciidoc is maybe a bit more standard jboss-y; is there already asciidoc/docbook that could be repurposed from RHQ? It might be easier to share content between RHQ Metrics & RHQ with the asciidoc / docbook route?

[theute]

RHQ doc is using Confluence (which can export to docbook), there is this RHQ Metrics page already: https://docs.jboss.org/author/display/RHQ/RHQ-Metrics

AsciiDoc is better suited to then transform to DocBook (I don't think there is an easy way to go from GitBook to Docbook) but requires a bit more work to handle the publication.

GitBook seems to be an easy start but may require us to convert to something else later (Using something like http://johnmacfarlane.net/pandoc/ and likely a lot of manual fixing).

[tsegismont]

Le 02/07/2014 12:02, Thomas Heute a écrit :

AsciiDoc ? (How/Where to publish)

+1. The documentation code can be added to the the rhq-metrics repository.

As for publishing we can start with Github Pages and then use the

project website when we get to a final agreement on the project name.

Github has a Maven plugin for publishing content to Github Pages (I use

in the Maven Plugin for Agent Plugins). So it's very easy to make this

part of release process.