Uploaded image for project: 'jboss.org'
  1. jboss.org
  2. ORG-1127

Allow more versions of project documentation in authoring Confluence

    XMLWordPrintable

Details

    Description

      Since switching to Confluence for the Infinispan docs (which we're pretty happy with) we've been thinking about the ways to handle multiple versions of the docs, for each release of the project.

      I've evaluated the docbook export which you recommend, alongside other options such as export to PDF/HTML, copying the space or copying a subtree of pages. Conclusions from the team are:

      Use markup inline (feature available since XXX)
      ------------------------
      - Fixes are very hard
      - Will get messy quickly
      - Error prone
      - hard for use to read
      + No infrastructure needed

      Conclusion: Not suitable, it's just too messy

      Export to static format (PDF/HTML)
      ----------------------------------------------
      + Confluence / Scroll Wiki make this easy to achieve
      - docs cannot then be fixed post release

      Conclusion: Not suitable, lack of post release edit is a killer

      Export to docbook
      ------------------------
      + Good idea in principle, as it allows us to use existing infra such as git to store docs from then on
      - Requires two different approaches to edit docs depending on what version they work on, which is confusing for people
      - current process is very manual (export manually, transform manually, add release info manually)
      - requires "double qa" - we check all the docs on confluence to make sure they look nice and then have to do so again for the exported version

      Conclusion: Not suitable, it's good idea, but current process is too manual, will re-evaluate when this is improved

      Copy subtree of pages
      ------------------------------
      + Fit's structure well as it keeps everything within a space
      + Allows post release editing within confluence
      - Plugin for this looks unsupported
      - Would need to be configurable to rename pages and update all links including includes etc.

      Conclusion: Not suitable, plugin isn't mature enough, otherwise a good approach

      Copy space
      ---------------
      + Structure is fine
      + Allows post release editing within confluence
      + Plugin looks stable, no naming issues
      + This is the approach taken by others who use confluence for docs (including atlassian)

      Conclusion: This looks like the best option open right now.

      Can you let me know what you think?

      Pete

      Attachments

        Issue Links

          Activity

            People

              velias@redhat.com Vlastimil Eliáš
              pmuiratbleepbleep Pete Muir (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              8 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: