Content re-use and automated publishing via Confluence Command Line Interface

This post is about the Confluence Command Line Interface, a tool developed by Bob Swift, and the way we’ve used it to solve a tricky requirement. We needed to copy a large amount of existing documentation for a number of products, and make that documentation available to a specific set of customers. We needed only part of the existing documentation for each product, and we needed to copy it regularly and repeatedly after major or minor updates. A prime candidate for content re-use and automation.

Our target audience is the customers who use our ‘OnDemand’ line of products: pre-installed and configured sites in the cloud. Therefore, large parts of the documentation for each product are applicable to these customers, but a small proportion of the documentation is irrelevant to them. For example, they don’t need to know how to install the product, and some of the configuration options are not available to them. This means that we needed conditional publishing as well as content re-use. We have used the Confluence Command Line Interface (CLI) to craft a solution. This is a specific use case, but I think the CLI is an excellent tool with wide application. So I’m writing to let you know about it.

The past

Until last week, our OnDemand documentation space contained just the introductions and overviews for people using the cloud-based products. For the product-specific documentation, we gave people a set of links to click, which sent them to the full set of documentation for each product.

When people went to the JIRA OnDemand user’s guide, for example, they would click a link and find themselves in the full JIRA documentation. They clicked happily around, searched with enthusiasm, and started reading about features that are not relevant to OnDemand sites.

The present

The OnDemand space now includes copies of all relevant pages from the Confluence, JIRA, Bamboo, FishEye and Crucible spaces. Pages that are irrelevant (such as the installation and plugin guides) are not included.

How did we do it? We used Bob Swift’s Confluence CLI to push the required pages to the OnDemand space. The CLI is a command line client that you run from your own computer. Just unzip it, give it the address of the Confluence server and a username/password to work with, and Bob’s your uncle. It uses Confluence’s remote API to access and update the data. One of the things that the CLI can do is copy pages from one space to another. If the page does not exist in the destination space, the CLI will add it. If it does exist, the CLI will update the page by adding a new version of the page. Upon request, the CLI will handle attachments in a similarly sensible way.

We have a number of batch files, one for each product, each containing a list of commands that copy all the relevant pages from the product documentation space to the OnDemand space. We built the batch files by hand, from our knowledge of the pages that are applicable to the OnDemand customers.

The future

In the medium term, we will continue using the CLI solution to update the OnDemand docs. For each product release, we will:

• Update the CLI commands as required, adding new pages that need to be copied and occasionally removing pages that we don’t need any more. Note: We can leave all the pages in the list, whether they’ve been updated for the new release or not.
• Run the CLI batch file when the new release has been published in the product documentation space. This will copy across all the updated pages for the new release into the OnDemand space.

We’ll also use the CLI solution to update the OnDemand pages at random times, when we’ve made valuable changes to the product docs during routine maintenance or in response to requests from customers or support.

More conditional publishing coming soon. The CLI allows us to pick and choose the pages that we copy to the OnDemand documentation space, simply by including or excluding the page from the CLI batch file. But there are times when just part of a page needs to be different in the OnDemand documentation and the product documentation. We’ll do that via inclusions. For example, this set of navigation instructions is re-used in a number of pages: Navigating to the Administration Console. We’ll be able to have different instructions in the OnDemand space and the Confluence space, to reflect the fact that the navigation menus are slightly different in the cloud-based products.

You can already see some examples of this method of conditional publishing via inclusions. For example, the Confluence documentation has a re-usable page about prerequisites for the Confluence Office Connector. The OnDemand page is shorter than the full product page, because some of the configuration is done automatically for OnDemand sites.

And soon after that… This new solution also puts us in a good place for the implementation of the Scroll Versions plugin, which will bring us more conditional publishing features as well as sophisticated version control. While implementing the CLI solution, we’ve learned a lot about the effects of having duplicate page content in two spaces, and figured out how to find duplicate page names across spaces. We’ve formulated our content re-use strategy, and made design decisions such as changing the search function so that it displays results from a single space only. We’ve also learned more about our content, which has to be a good thing!

References

An earlier post introduces the Confluence Command Line Interface and how to use it: Confluence CLI for bulk actions like deleting or publishing pages.

The CLI documentation includes some useful examples and a list of all the available actions and parameters.

The batch files for our CLI solution are on Bitbucket: AOD CLI.

We make frequent use of the Include Page macro for content re-use, by including the content of one page into another. This dovetails neatly with our new CLI solution. I’ll write a more detailed post about this some time.

Thank you to Bob Swift for the awesome Confluence CLI! And kudos to our technical writers, who have undertaken a gleeful transmogrification into the Tech writing AOD bot.