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:

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:

The subtasks on our JIRA template issue

This is an example of one of the subtasks:

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. 😉