Wiki docs – release management

A wiki is a living organism. Its content is dynamic, continuously updated, commented on, subscribed to and watched by thousands of people all over the world. How does this work with technical documentation that is release-specific? Can you baseline your documentation? What if you are documenting a piece of software or some other product that goes through a regular release cycle, and your customers need to access the documentation which corresponds to their specific version of your product? This is elementary release management, bread and butter to technical writers. But can a wiki do it?

This week I created an archive space on our Confluence documentation wiki, in preparation for an upcoming major release of Atlassian Crowd. So now’s a good time to talk about the way we manage the technical documentation in correlation with our software releases. And to find out how other people are doing it.

Let’s say your wiki pages tell people how to use a toaster. And let’s say the very latest toaster in the product line, due out before Christmas, has a bright new quick-toast button. But there are thousands of customers out there who already have the original product and rely on it heavily – even without the shiny new button. What should your documents say about the button? Even more complicated: What if the toast-insertion mechanism is about to change from the old shove-it-in-by-hand method to a fancy new sliding widget?

There are a few strategies:

  • Have separate documents for each version of the toaster.
  • Have only one document, describe all features including the newest, and add a note that the quick-toast button is available only on the latest toasters. Also explain how the toast-insertion functionality has been enhanced. You could even hint that your customers should consider upgrading their toaster.
  • Ignore older versions of the product, and only give instructions on using the very latest version.
  • Any more? Let me know how you’ve done it.

Our choice:

We’ve chosen the first option. The second might result in a long list of notes, tracking a feature’s changes through the various releases of the product. This might become confusing in the long run. (But the second option does have its attractions – it’s a lot simpler, from the point of view of document management.)

We make use of ‘spaces’. A space is a sort of wiki-within-a-wiki, and is part of a Confluence wiki. If your wiki doesn’t allow spaces, then you might consider having separate wiki instances for each software release.

Here’s how we do it:

  • The ‘main’ documentation space always contains the documentation for the latest release of the software – such as Crowd.
  • ‘Archive’ spaces contain the documentation for each previous major release of the software – such as Crowd 1.0.
  • We also provide PDF, HTML and XML versions of the documentation – here they are for all the Crowd releases.

Update November 2009:

  • We use the Copy Space plugin to make the archive copies of the space. Note that the Copy Space plugin isn’t supported by Atlassian. But we use it.πŸ™‚
  • If you like, you can vote for or comment on our JIRA request to have the plugin shipped with Confluence, or at least supported.

The fly in the ointment.

That sounds quite simple, huh. But as usual, there are some idiosyncrasies which need a bit of working around. The tricky bit is in the first bullet point above – the ‘main’ space always contains the documentation for the latest software release.

So we can’t start adding information about the new release until release date. And we can’t archive off the current space or create a new ‘draft’ space which will take its place at release date.

Why not? Two very important reasons:

  1. Lots of people all over the world have hyperlinks into the documentation space, and subscribe to RSS feeds from it, and add ‘watches’ to pages on it, and comment on it. So we can’t archive the existing main space – that would break all their links and stuff.
  2. The wiki is alive. As well as the technical writers, we have support staff and developers continuously updating the content. If we created a draft space and then later used it to replace the current space, we’d lose all updates made since the draft was created. And if we ‘froze’ the current space, the wiki wouldn’t be alive.

The fly catchers.

How do we solve the problem? Well, it takes a fair bit of organisation, and the help of a couple of tools.

When documenting new features for the upcoming release, we create pages in the wiki and ‘hide’ them from public view using Confluence’s page restriction functionality. And we make a note to ‘unhide’ the page on release date.

When we need to add or change existing pages due to changes in the upcoming release, we can’t make the change until release date. So we make detailed notes about the changes that need to be made.

Some time before release day, we make an archive copy which will become the documentation for the previous release (now still the current release).

On release day, we first update the space description so that it refers to the latest software release. Then we go through our ‘unhide’ and ‘update’ notes, applying the changes to the main space.

Where do we make the notes, you may ask? In a JIRA task, of course.

Summing it up:

Yes, a wiki can handle release-dependent documentation reliably and usefully. It’s pretty similar to using any other documentation system – find the tools that will help, and then make a plan to make them work to your requirements.

Wikis save trees.

Completely off topicπŸ™‚ but I wanted to add a pretty picture because release-management is a bit of a dry subject. Here’s a gum tree we came across this week, while walking through the Manly Dam parklands. The multi-coloured bark is a lovely sight, and quite common too. Does anyone know the name of this tree?

Multicoloured bark on a gum tree

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 17 November 2007, in atlassian, Confluence, Crowd, environment, technical writing, trees, wiki and tagged , , , , , , , , , , . Bookmark the permalink. 21 Comments.

  1. What are some of the challenges of using the Wiki? What are some situations where using a Wiki would be unadvisable? Thank you.

  2. I’m not great at tree identification, but I’m pretty sure that’s an angophora of some sort. http://www.flickr.com/search/?q=angophora&w=all&s=int
    http://en.wikipedia.org/wiki/Angophora

    They do lose their bark like that. Often you’ll see a big pile of bark around the base of one.

    I think you skipped a couple of problems with using archived spaces for previous versions of documentation.
    * Confluence doesn’t actually provide a supported mechanism for archiving spaces. (note the massive disclaimer on the Copy Space Plugin page.)
    * Searching the wiki for documentation invariably returns multiple copies of the same page except where the search is limited to a space.

  3. Good article !

    I agree that the best is to branch into two versions of your product documentation each with a separate lifecycle.

    But in order to avoid duplication, the granularity of your documents becomes very important.

    Within your wiki you should be able to show where a particular section is reused.

    If you are able to manage/control this reuse,
    comments and changes on the topic/section will not be lost across different versions and formats.

    I have not seen “topic based” authoring WIKI systems.

    So I believe more into structured authoring environments with a publishing mechanism into a wiki.

    The search engine of your wiki, will be capable of avoiding duplicate entries in the search result, if the indexing took into account the different relations between the topics of the documents.

  4. Great tips, especially since I really dont know much about how the wiki works.
    -Jack

  5. Do you use any content-management system “behind the scenes” before moving documentation into Confluence? Or does content start in the wiki from scratch?

  6. Hallo there Paul
    The content starts in the wiki from scratch. We do all our authoring, review, publication and maintenance on the wiki directly.
    Cheers
    Sarah

  7. Hi Sarah,

    thanks for this article! Wow, I have questions. What tool do you use to create PDFs from multiple Confluence pages? Also, how does your writing team manage your content in terms of just remembering where all the pieces are? Is all the content in TOCs so that the writers can find pieces quickly to update them?

  8. Hallo Ann

    Great questions!

    We use the Confluence ‘space export’ functionality to create our PDF files. You need ‘space export’ permission for the space. If you have that permission, you will see the space export features (PDF, HTML and XML) on the ‘Advanced’ tab in your ‘Browse space’ option. The feature allows you to choose the pages you want to export — the whole space, one or more page trees, or selected pages.

    We use a variety of methods to find our content. Each of the tech writers is responsible for a set of document spaces, so we have a pretty intimate knowledge of the content. We and other people use the Confluence search a lot, to find the pages we need to update. And yes, we have a left-hand navigation bar that shows the table of contents for each space.

    Cheers
    Sarah

  9. Sarah, I have a simple question on documentation release management.
    You wrote two things:
    1) you (at Atlassian) use the Copy space to create an archive for the previous product version
    2) you use {include}, {excerpt} macros for content re-use (I’ve read from your article in southern communication)

    So the question is –
    When you create an archive copy of a space, do all pages have only space-relative links? Must have? Is it a restriction of space organization of pages?

    Is there any risk of changing actual pages that will affect archive pages, where the actual page is included?

    • Hallo Katya

      Good question! We tackle this on a case-by-case basis. Most of our includes are indeed from the same space, so that they play nicely with the version control. When we have documentation that is not version-specific, then we do include content across spaces.

      We know our content fairly well, so we know how the included sections are used. We make sure to put them all in a special “area” of the wiki and to give them a special page name. (We use the underscore at the start of the page name, to remind us that the page is special.) This helps to prevent us and other authors from editing the included content by mistake. In case you haven’t seen it, I wrote a post a while back about content re-use on a wiki. I hope that helps.πŸ™‚

      Cheers
      Sarah

  10. Thank you very much for the advice – I have not seen your post about content re-use in wikis indeed!

    I’ve taken into account your inclusions library trick – I think I will apply it too.

    But another thought came into my head – is there any mechanizm or Confluence plugin to unbranch “includes” between spaces, which will replace {include} with the actual text? It is the standard functionality of a source control, that would be nice to have this feature for wiki docs.

    Unbranching can simplify the process – I just create a copy of the space to make an archive, then replace includes with the actual text and voila! I get an archive, which will not be affected with changes I make to the next, under construction version of the document.
    I’ve found the HTML Include Replace plugin https://plugins.atlassian.com/plugin/details/4885, however it imports content from external websites, it is not the essential what I search.
    I also found the Confluence Archiving plugin
    https://plugins.atlassian.com/plugin/details/123 but it does not provide this functionality too.

    What do you think?

    • Hallo Katya,

      That’s an interesting idea. An additional thought would be to suggest that it’s optional: so, when you use the copy space plugin to copy the space, it asks if you want to auto-replace the content of the {include} and {excerpt-include} macros with the static text.

      One thing though: At this time in the wiki development phase, I think quite a few people might say that the feature request goes a bit too far into the CMS side of things.

      If you like, you could raise a feature request for the Copy Space plugin, to add this improvement.πŸ™‚

      It’s great to hear your ideas. Thanks for dropping in!
      Cheers
      Sarah

  11. Thank you for the answer, Sarah!

    I’ve created a feature request on Copy Space plugin:
    https://studio.plugins.atlassian.com/browse/CPSP-27

    Please vote for it, if you are interested in this functionality.

    I understand that the plugin is not currently supported, however “hope springs eternal in the human breast”πŸ™‚

    The only question is not clear for me – why people do not want to add functionality to wiki, which will allow author to structure content in easiser way? Some CMS functionality does not contradict with wiki collaboration. I understand that wiki is not a CMS, but what is primary – keep to wiki or CMS principles, or tend to create a universial and useful authoring area?

    • Hallo Katya,

      You’re right, of course: it would be awesome to have CMS-like functionality in the wiki. There is some merit, though, in the counter-argument that it’s a good thing to keep a wiki simple. From the users’ point of view, simple is good. And from an maintenance point of view, the more complexity we build into the wiki, the more testing, documentation and maintenance is required. This takes up developer time, and it can also just slow down the development of other new features because they all need to work together.

      That said, though, as a technical writer I’m totally with you. From my point of view, content is king. It’s hard to see how people could argue against features and improvements that make better and more consistent content!

      Great stuff, creating that issue. I’ve voted for it and I’ll point it out to the other tech writers here at Atlassian too. Tweeted too.

  12. Thanks for your kindly support, Sarah!

    The feature request is actively commented.

    I hope we will find the solution. Might this feature be useful to Atlassian tech writers?

  13. So, you’ve been doing things this way for a while now. I’m curious, if you had the opportunity to start over again, would you do it the same way?

    Specifically, I’m wondering about whether or not to maintain the top level, always evolving, non-versioned space:

    * product (currently holds v3 content)
    * product-v2
    * product-v1

    Is it better to do that, or is it better to always have a spaced named with a specific versionFor example, Instead of the above, would it be better to have?:

    * product-v3
    * product-v2
    * product-v1

    I think my biggest concern with migrating content in and out of a * product space is external links to content (including links from our application to specific pages in the wiki): They will likely produce unpredictable behavior over time (broken link, content that doesn’t speak to the right version of the app, etc…). I want external referrers (including our application) to have links that won’t change over time. On the other hand, I kind of like the idea of being able to always link to the most recent content, even if that content hasn’t been written yet. Maybe that’s where the {spacejump} macro comes in?

    Perhaps a schema like this would be better?:

    * product (navigating to this space redirects to most recent space)
    * product-v3 (links from v3 of app are hardcoded to point to this space)
    * product-v2 (links from v2 of app are hardcoded to point to this space)
    * product-v1 (etc…)

    At any rate, hope you can follow me. I know it’s long. Just have to make a decision here and you’ve had some experience doing it one way, so I thought I’d check to see if you still like it.

    -Michael

    • Hallo Michael

      It’s a thorny question, and I think the answer depends very much on the needs of the readers and how they will use the wiki.

      The way we do it, as you described, is that the main space always documents the latest version of the product. In many cases, this is actually the simplest way to ensure that we don’t have to keep changing external links, because most external links need to point to the latest version anyway. It’s also best for many of our customers who subscribe to RSS feeds, add “watches” to pages so that they can receive email notifications when something changes, and add comments to the pages. All those readers would need to change their feeds and watches whenever they changed their version of the product.

      On the other hand, perhaps it’s less burdensome for them to do that, if their organisations don’t upgrade their products regularly. For them, it would actually be better to stay subscribed to a given version of the documentation.

      I think, given the choice to start afresh, I’d probably advocate a solution more like the one you propose. It’s certainly simpler and easier to maintain, from our own point of view. And perhaps from the customers’ point of view it’s easier too. Perhaps we would even have a third space that contains the volatile documents that people may like to watch, subscribe to and/or comment on. Examples might be the release notes, FAQ pages and security advisories. These are perhaps not as version-sensitive as the user documentation.

      At the moment, we’ve moving towards a much more agile approach where the “main” space starts documenting the new version even before it’s generally available. We may up the version of the space when the next version goes into beta, or even early access (EAP). In such an environment, it certainly does make more sense to have a fixed space for each version.

      So, basically, it depends whether the customers value the community side of the documentation as much as the pure documentation side of it. If the community aspect is important, do you have enough technical writers to monitor all the versions all the time? We only monitor the current version, and only allow comments/updates on the current version. People’s subscriptions, comments and watches all go into that one, constant space.

      Phew! Long reply.πŸ™‚ I hope it helps!

      Cheers, Sarah

    • MaryAnn Rapuano

      Hi Michael – I was wondering what decision you finally made concerning the situation described above. Is there a way to set up the redirect to the “product” space in your schema inside Confluence or is this a job for DNS? Thanks.

  14. Kamesh Challa

    Thank you very much for the post and the discussion. I’ve a challenge with Agile development, where the design document could go through revisions depending on the features I’d want to develop as part of a release cycle. I think it could be very challenging and difficult to manage Confluence in the long run with several projects multiplied by several releases (I’ve few projects running concurrently). I guess, cross space comparison (between “Release 1.1 space” to “Release 1.2 space”) of wiki pages could be very challenging!!

    Do you see my challenge any differently?

    I think the problem I mentioned here is not unique to Confluence but wikis in general.
    Greatly appreciate your thoughts.

    Cheers,
    –Kamesh

    • Hallo Kamesh

      You’re right, it does get challenging when you’re faced with documenting a number of small projects. This is especially true when the projects contain features for the same project, and when the release dates of the projects are unknown until date of shipping, and when release dates overlap. That pretty much describes an agile environment. We’re facing that situation more and more in our team. Even more, we have to cater for different editions of the same product – customers may install it themselves or use the hosted version in the cloud.

      Core Confluence doesn’t have the functionality we need in this environment. We are therefore working with K15t Software to develop a plugin called Scroll Versions. It will add the required features to the wiki. Exciting stuff! K15t expect to have a beta or 1.0 version available soon. Stay tuned for news.

      Cheers, Sarah

  1. Pingback: Solving a problem with the Confluence Copy Space and Gliffy plugins « ffeathers — a technical writer’s blog

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: