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

    Documentation

    theute
    theute Jul 2, 2014 6:01 AM

      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.

      • 403 Views
      • Tags:
        • 1. Re: Documentation
          jastrachan
          jastrachan Jul 2, 2014 6:37 AM (in response to theute)

          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?

            • Actions
          • 2. Re: Documentation
            theute
            theute Jul 2, 2014 7:44 AM (in response to jastrachan)

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

              • Actions
            • 3. Re: Documentation
              tsegismont
              tsegismont Jul 2, 2014 8:16 AM (in response to theute)

              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.

                • Actions