JIRA cloning to create a template for repeated documentation tasks

At each major release of the software that we document, a technical writer has to perform a number of tasks. Many of the tasks are repeated at every release. My team uses JIRA to keep track of our documentation tasks. Last week I decided to try using JIRA’s cloning functionality to create a template, consisting of an umbrella issue with a set of subtasks, that we can clone for future releases. It’s looking like a useful idea, so I’m blogging about it in case other people find it helpful too.

JIRA is a bug-tracking and project management tool. Up to now, when preparing for a release we’ve created the documentation tasks in JIRA by basing them on the tasks from the previous release. This worked well, but we did spend a fair bit of time sorting out which tasks were required for every release, as opposed to the feature-related documentation bound to a specific release. We also had to remove comments like “Completed this task on Monday 1 April,” or “Reviewed by PM and dev.”

What is JIRA cloning?

In JIRA, you can clone an issue (task) to create a copy of the useful parts of that issue. When you clone the issue, JIRA creates a new issue with the same summary (title) and description as the one you’ve cloned. It copies across the information from other relevant fields and sets the status of the new issue to “open”. The JIRA documentation lists all the fields that are copied to your new issue.

You can also choose to clone the subtasks — and that’s where it gets really handy!

Creating the template for documentation tasks

To create my template for use in future releases, I cloned my documentation task from the previous major release plus all its subtasks.

Then I deleted the subtasks that related specifically to the past release. I was left with an umbrella issue and a number of subtasks, one for each of the tasks that need to be done at every release.

Next I adjusted the issue summaries and descriptions to make them generic, so that they no longer refer to any specific release number.

Now that we have a template that other technical writers will be using, I decided to expand the descriptions too. It’s useful to include a bit more explanation than I have done in the past, when the descriptions were mostly just a reminder to myself of what needed doing.

Here’s that our umbrella template issue looks like now. The product I’m documenting is called “Confluence” and I’m using the convention “x.x” to indicate a release number that needs to be filled in when we create a real issue based on the template:

JIRA cloning

A JIRA issue used as a template

Below is a list of all the subtasks on the above issue. We will use each of the subtasks as a template too:

JIRA cloning

The subtasks on our JIRA template issue

This is an example of one of the subtasks:

JIRA cloning

A JIRA subtask to be used as a template

As you can see, the subtask contains quite a bit of detail about what needs to be done.

You’ve probably also noticed that all the issues have a status of “Resolved”. I did that just so that the template issues don’t keep popping up and demanding to be addressed. But when we clone the issues at our next major release, JIRA will automatically give the new issues a status of “Open”.

Using cloning to prepare the documentation tasks at our next release

At the next major release, we can just clone our umbrella template issue and say “Yes, please” when JIRA asks if we want to clone the subtasks too.

We will then go on to add more subtasks to our new issue. They will be the tasks specific to the release, such as documenting new features and changes to supported platforms. The template issues will remain untouched, ready to be cloned again next time round.

No doubt we will find tasks and improvements to add to our template issues from time to time as well.

The benefits of having a task template

This will save us a lot of time: A couple of hours per release!

The template will help us make sure that we don’t forget any of the things that need to happen at each release. It will also give new team members a concise overview of what’s involved in a documentation release.

The template also gives the product managers and development team a good insight into the tasks that the technical writers need to do in order to publish and maintain the documentation. Many of the repeated tasks revolve around ensuring that we have version-specific documentation for customers who do not upgrade to the latest release, supplying downloadable versions of the documentation for customers who cannot use our online documentation, updating the tutorials that are shipped within the product itself, and generally keeping the documentation ticking along.

It’s not uncommon for people, other than the technical writers, to overlook this sort of necessary but behind-the-scenes task. ;)

About these ads

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 12 April 2011, in technical writing and tagged , , , , . Bookmark the permalink. 11 Comments.

  1. Great post. I was just developing more or less the same for weekly operations of a marketing and ecom optimization team.

    I was looking at the tasklist in Confluence, but this is better. And the idea about resolved for the template is just great.

    • Hallo sune
      Thanks for your comment! I’m so glad the tip is useful. A few Atlassians have commented that they find the idea useful too. :)
      Cheers, Sarah

  2. Great article. Bryce did a similar one recently as well.

    I have raised https://jira.atlassian.com/browse/JRA-25037. I think variable replacement at the clone time would help make the templates an even more powerful feature. What do you think?

    • Hallo Brad :)

      That’s an excellent idea! We’ve already saved ourselves a few hours per release by using the “template and clone” technique. Adding these variables would save us more time still.

      It will also make the clones more usable. I suspect that many people will avoid having to use the technique of “X.X”, just so that that they don’t have to manually replace all the Xs as I do. So, if the variables are available, people are more likely to add them and thus make their clones more readable and meaningful.

      I’ve voted for and commented on the issue.
      Cheers, Sarah

  3. I liked the clone idea in creating templates. I am planning to propose this idea for our documentation team.
    Adding in variables is a very helpul one. Hope this comes along soon.

  4. Great article really like the idea with cloning thanks for the good post :)!

  5. Hi,
    We have released our new plugin – Issue Template. In this plugin you can create templates as a ordinary issues with predefined fileds & customfields values.

    Available at https://marketplace.atlassian.com/plugins/com.intenso.jira.issue-templates

    Cheers, Kris

  6. Hi Sarah,

    We are re-thinking this whole thing as re-usable checklists to document how-to’s – not necessarily just for cloning tasks. Here’s a thread on that:

    https://answers.atlassian.com/questions/245363/re-usable-checklists-and-capturing-best-practices-within-confluence-and-jira

    Anyway, we hope to make a plugin to this effect which links to our main app – with analytics to measure and improve processes as well. If you’re interested, there’s a newsletter at the bottom of:

    http://tallyfy.com

    I should clarify that this is not task management, it’s purely re-usable “how to’s” and testing scripts, etc.

    thanks
    Amit

  7. This is exactly what i need. Thank you!

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

Follow

Get every new post delivered to your Inbox.

Join 1,495 other followers

%d bloggers like this: