3 Replies Latest reply on Jul 2, 2014 8:16 AM by tsegismont

    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.

        • 1. Re: Documentation
          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?

          • 2. Re: Documentation
            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).

            • 3. Re: Documentation
              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.