Blog Archives

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

More about content re-use on a wiki

A while ago I wrote a post about content re-use on a wiki. Just recently I’ve discovered that the {excerpt} macro has a handy parameter: “hidden=true”. So I thought I’d tell you about it.

In  Confluence wiki, you can dynamically include content from one page into another page. These are the macros to use:

  • Use the {include} macro to include a whole page into another page.
  • Use the {excerpt} macro to define a re-usable chunk of text (an ‘excerpt’) that is part of a page, then include that excerpted text into another page using the {excerpt-include} macro.

My recent “eureka” moment happened when I noticed the “hidden” parameter in the {excerpt} macro:

{excerpt:hidden=true}Blah blah blah.{excerpt}

If you specify “hidden=true”, the content between the {excerpt} tags will not be displayed on the page where the excerpt is defined. It will, however, be displayed on the page where the excerpt is used via the {excerpt-include} macro. Magic!

Here’s an example of a page that does just that. It’s from our SharePoint Connector documentation: _Access Confluence using IWA with IIS

I’ve added some text to the page, explaining that the content is hidden and telling people how they can see it if they really want to. Here’s a screenshot of the same page (click the image to expand it):

More about content re-use on a wiki

More about content re-use on a wiki

Why on earth would you want to hide the content of an excerpt?

It stems from the way we are using content re-use in our structured technical documentation. My earlier post goes into it in detail. Here’s a quick summary.

We create a special “area” of the wiki, which we call the “inclusions library”. It’s not really anything special. It’s just a set of pages that hold the chunks of content (text, images, etc) that we will use more than once, on various wiki pages. We also use an underscore at the start of the page names, to remind us that the pages are special. This helps to prevent us and other authors from editing the included content by mistake.

The thing about a wiki, though, is that people may stumble across the pages in our “inclusions library”. They may wander in via Google search, and not realise that this page is just part of a set of instructions. Sure, it’s got a weird page name. But hey, it’s a wiki. What do you expect?

It may even be a bit traumatic for them if they start following the instructions, without having performed the preceding steps. 😉

Here’s one of the pages that use the excerpt from the above page. This page is neatly in place in the full installation sequence: Access Confluence using Integrated Windows Authentication via IIS with SP 2010. Much less chance of our poor Googler going off the beaten track.

I think the “hidden=true” parameter is pretty neat. I don’t know why I didn’t notice it before. Now you know about it too!

Content re-use on a wiki

You’re writing a page on a wiki and you realise that some words you wrote just the other day would make sense here too. But where oh where are they? Or you want to include a picture, such as a logo, that’s used on other pages all over the show. Of course, you could just copy and paste. But can the wiki be more sophisticated than that?

I use the Confluence wiki for technical documentation. Some parts of this blog post are very specific to Confluence, because I thought other Confluence fans might find them useful.

For people who aren’t using Confluence, the first bit and the last bit of this blog post are for you 😉 The basic idea is that wikis (at least some of them) do allow content re-use. And the question at the end is, do you have any experience or hints about other wikis?

A quick note on terminology: In this blog post I’m using the words “content re-use” to mean the re-use of text or pages within the wiki itself. I’m not referring to single-sourcing of content across multiple media.

Why re-use content?

It saves time if you don’t have to keep re-inventing the word 😉

Another problem with duplicated content is when something changes. You could easily miss some of the pages that need updating. So you run the risk of contradiction, incompleteness, and content which is just plain wrong.

If you want to translate your documentation into another language, it’s a great advantage to have as few words as possible. If you plan to engage someone else to do the translation for you, they will probably charge by word count or page count, so it could save you some $$ too.

Including content from other pages in Confluence

Confluence allows you to dynamically include content from one page into another page. You can include a whole page into another one, using the {include} macro. You can also define an ‘excerpt’ on a page, and then include that excerpted text into another page using the {excerpt-include} macro.

That’s old hat. We’ve been doing that for years 🙂 So why am I writing about it?

Because we’ve started doing things a bit differently recently, and I thought other people might like to know about it.

At first, we did things like this:

  • We defined an excerpt on the first page that happened to contain the wording we wanted. Then we included that wording into other pages as needed.
  • Or we included an entire page from anywhere in the wiki into another page in the wiki.

There are a few disadvantages to doing it that way:

  • When a whole page is included in another page, there’s no indication that the content is being re-used elsewhere. So anyone might change or even delete the page without realising they are affecting other pages.
  • For both partial and whole includes, anyone might change a page name without realising that they are breaking the {excerpt-include} and {include} macros. (Confluence does not automatically fix changed page names in macros, only in links.)
  • Re-used content is scattered throughout the wiki.

The better way

Now we’re using a set of pages called an “inclusions library”.

Here are some examples in our documentation:
Crowd Inclusions Library
Confluence Inclusions Library

Some notes about the inclusions libraries:

  • The pages are located at the root of the wiki space, not under the “Home” page. This means that they will not appear in the table of contents on the left and they will not be picked up by the search in the left-hand navigation bar either.
  • The pages will be picked up by other searches, because they are just normal wiki pages.
  • For all new pages, we have decided to start the page name with an underscore e.g. “_My Page Name”. This indicates that the page is slightly unusual, and will help prevent people from changing the page name.

Including images from a central image repository in Confluence

You can attach your images to a single page and then include them into other pages. This means that the images are in one central place, instead of attached to an unknown number of pages. Here’s an example of an icon repository in our Atlassian IDE Plugin documentation.

What about you?

I did a very quick search to see what other wikis offer. The Socialtext documentation says you can include the contents of a page into another page. So does TWiki. That’s as far as I got.

I find this sort of feature offering really interesting because it shows that wiki creators are designing features for technical documentation and other formal writing, as much as the less structured collaboration use that is the wiki’s traditional comfort zone.

Have you used any content re-use features as part of the design of your documentation system, or are you using a wiki in this sort of structured way?

Re-use of a different kind

Here’s a ring-tailed possum making use of our telephone lines as a handy path from A to B.

Content re-use on a wiki

Content re-use on a wiki

Content re-use on a wiki

Content re-use on a wiki

%d bloggers like this: