Skip to end of metadata
Go to start of metadata

Confluence allows for rapid creation and editing of content using wiki markup during the documentation authoring process.
However in order to maintain the content following a project release, output it in different formats including HTML / PDF and translate it into different languages, it's necessary to perform some steps during release.

"Confluence as editor" use case

In this use case Confluence is used only as latest documentation version editor. In order to maintain the content following a project release, output it in different formats including HTML / PDF and translate it into different languages, it's necessary to export the wiki markup to DocBook XML and check it into a Version Control System. This is typically done by the Project Lead or a member of the project team following the steps below:

  1. Export the Space content into a DocBook XML zip file in a well-defined structure using the JBoss DocBook Export plugin.
  2. Add release information to the exported DocBook XML files.
  3. Commit the DocBook XML into a source code repository (e.g. Subversion, GIT) alongside the project source code.
  4. Generate HTML and PDF documentation from the DocBook XML using publishing tools documented in JBoss Documentation Guide provided by Press Gang project.
  5. Upload the released documentation to http://docs.jboss.org.

Once project documentation has been released then the Space content can be edited, rearranged, or deleted as necessary to create the next version.

To export space content into DocBook xml a user must have the Space - Export permission within a space.
Content authors must follow the rules described in the Markup Guide and Style Guide to obtain consistent high-quality documentation!

"Multiple documentation versions in Confluence" use case

In this use case Confluence is used not only to edit latest documentation version, but also to show and edit documentation for already released project versions. So one space is used to edit latest version of documentation, and in release time this space is copied to new one to snapshot documentation for released version.
This is typically done by the Project Lead or a member of the project team following the steps below:

  1. Copy the "Latest documentation version" Space content into "Release specific documentation version" Space.

Released version of documentation in separated space can be updated independently then to correct it, exported into DocBook XML for output it in different formats including HTML / PDF and translate it into different languages etc. Steps for this are same as in "Confluence as editor" use case, but performed on version specific Space.

All documentation spaces for all versions of project are assigned under one root Space dedicated to this project to be better organized on Confluence main page (SubSpace confluence plugin used here). Main page of this root space shows automatically generated list of available versions with links to distinct version of documentation.

If you plan to use confluence this way, contact the JBoss Community Team to create necessary root space for your project.
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.