Using JIRA to Track Writing Assignments

January 18th, 2012 | Posted in blog 28 Comments »

We had a couple of writing interns join our group this month. To track writing assignments for the technology blog, I’ve been using JIRA. JIRA is a bug tracking tool from Atlassian (the same company that makes Confluence). It’s typically used by software teams to track bugs during software development projects. You can add comments to items, assign items to team members, assign the items to sprints, create advanced viewing filters for the items, and more.

Since I’m using JIRA to track writing assignments, I have to live with a few compromises in terminology, but so far I like the system. Here are some details of how I’m using it.

Each item in JIRA is an article. I add only articles that we’re really going to write. (For general ideas that may one day be something we write, I put the ideas elsewhere.)

I assign the JIRA items to the writers who will write the article. If there is no writer, I leave the article unassigned.

I give each article a story point weight of about 10 points. Another section of JIRA allows me to define specific sprint release windows, and I organize sprints (based on weeks) to accept no more than 70 story points. This means that each sprint can only have 7 articles, assuming each article is 10 story points. However, I can also adjust the story points for each article. For example, short articles might be 3 story points, while longer articles might be 15 story points. Adjusting for the appropriate number of story points helps us avoid over-allocating work for the week.

In the JIRA item, I try to outline the general ideas the article should cover. I also add comments about each item, and the assignee receives an email notification with each comment and edit.

When an article is completely finished and published, I change its status to Resolved. Or if we decide to not do the article, I resolve or delete the article. The resolution statuses include Fixed, Will Not Fix, Duplicate, and some others.

I can assign different priorities to the articles — 1, 2, 3, 4, or 5. A priority 1 is called a “blocker.” Priority 2 is called “critical.” Priority 3 is “major,” and so on. (Here’s where the terminology doesn’t quite fit for writing assignments.)

JIRA’s filters are robust, but I am using them in a simple manner. I create a filter to show all items assigned to each intern, and then I save those filters as bookmarks. When I review and plan articles with the writers, we just select the JIRA filter and go down the list of what they’re working on.

I’ve tried various ways to organize and track writing assignments, and so far this one seems to work well. Of course no system works if you don’t actually use the system, and no system is perfect. I used to have little slips of paper pinned all around my cube. I’ve also tried Excel spreadsheets, as well as SharePoint.

But using JIRA to track writing assignments is particularly beneficial because familiarity with JIRA helps out with our involvement in project teams. In our IT department, many project teams use JIRA, and familiarity with JIRA makes it much easier to stay abreast of project news, releases, bugs, issues, and other details. Often the lifeblood of a software project is captured in JIRA, since this asynchronous sharing of information helps everyone on the team remain aware of what’s going on.

One thing I’m not using JIRA for is to manage the actual documents. While I could upload file attachments, I find that Dropbox is much easier. Dropbox is almost like a net file share drive. I could spend an entirely separate post describing how much I love Dropbox, but so that I stay on track, I’ll just say that I try to name the Dropbox folders the same as the JIRA item titles.

One other shortcoming of JIRA is that it doesn’t allow me to change the statuses of items in a customizable way (at least I haven’t figure out how to do it yet). I’d like to indicate various states of the article as they pass through the approval processes, but alas, the issues in JIRA are either Open, In Progress, or Resolved. (Perhaps it’s best to keep it simple.)

I’d be interested to hear what system you use to manage and track writing assignments.

Buffer

Archives

Antti says:

January 18, 2012 at 9:30 am

We also use Jira at Magnolia. We enter documentation assignments into a specific project and link them to development items as needed. We use the same priorities as developers do. We are not far enough to organize our work into sprints yet. Have you tried the Greenhopper add-on? Looks nifty in the video.

Tom Johnson says:

January 21, 2012 at 2:44 pm

Yes, I have the Greenhopper plugin installed. It is incredibly helpful, since it allows you to easily organize items into sprints, or releases.

Susan S says:

January 18, 2012 at 9:31 am

Interesting. I don’t use JIRA (or anything else, really) to keep track of writing, but I do use JIRA to track help desk inquiries.

Tom Johnson says:

January 21, 2012 at 2:44 pm

The software is robust enough to use in a large variety of ways. Using it for help desk inquiries sounds like it would fit well.

Phill G says:

January 18, 2012 at 11:28 am

We also use JIRA for tracking document progress, I have managed to customise the workflow and add different status for our documentation tasks. e.g. we have status for fact finding, writing, technical review, peer review and signed-off

I am a big fan of JIRA

Tom Johnson says:

January 21, 2012 at 2:43 pm

Thanks for joining in the conversation here. It’s great to hear how many different writers are using JIRA. I am actually surprised. I didn’t think it was that common, but it turns out that it is.

Mollye Barrett says:

January 18, 2012 at 11:31 am

JIRA is a great tool for tracking assignments but it also has excellent workflow capabilities. I use it to comment on a topic, provide links reference links and attach pertinent documents. Everything about an task/assignment is in one place and generating a report is easy. Great tool!

Tom Johnson says:

January 21, 2012 at 2:43 pm

I also like that everything is in one place, but if you have multiple versions of documents, doesn’t that get a little cumbersome to always upload them? I need to figure out workflows. Simply assigning items to other writers seems to work well enough. But we also have about 3-4 approval workflows that we need to route content through. It would be really useful to integrate some of my approvers into the workflow.

Patrice Fanning says:

January 18, 2012 at 12:56 pm

I like your idea of using Jira purely for tracking writing assignments Tom, although it’s not something I’ve considered. While I was working at SAP, there was a shift to the Lean development model. Jira was introduced as the tool of choice for product and scrum teams to track backlog items within and across sprints. I found that by including dedicated items and tasks for writers in Jira they became much more prominent and it was immediately clear when developers or other team members were holding things up on the documentation front.

Tom Johnson says:

January 21, 2012 at 2:41 pm

Yes, I’ve also found that developers take JIRA items seriously. When I want something done, I log a bug in JiRA for it. And then if I’m really feeling aggressive, I drag the bug to the next sprint. Crossing over into JIRA has been one of the most useful tools as a technical writer.

Sarah Maddox says:

January 18, 2012 at 6:11 pm

Hallo Tom

Nice post! I work at Atlassian, so you can guess which tool I use to track writing assignments.

You can change JIRA’s statuses, and also the transitions between the statuses. JIRA calls this the “workflow”. Here’s the documentation: http://confluence.atlassian.com/display/JIRA/Configuring+Workflow

And here’s a hint that was magic to me when I first discovered it. You can save a filter as a gadget on your dashboard. (This may help you get to the filters for the various students, instead of having to bookmark them.) Just go to the JIRA search page, and open an existing filter or create a new one. Click Search, to see the search results. Then click “Views” > “On Dashboard”. Follow the instructions to save the search as a gadget on your dashboard.

Note that you can add your own dashboard(s), which you can customise to be different from the default. You can also share your dashboard with other people. See the docs: http://confluence.atlassian.com/display/JIRA/Customising+the+Dashboard

Have fun.

Cheers, Sarah

Tom Johnson says:

January 21, 2012 at 2:39 pm

Thanks for the tip about dashboards and workflows. I have added filters as gadgets to my dashboard, and it’s helpful. I haven’t customized workflows yet, but eventually I will. JIRA is a super powerful tool, and it takes some figuring out. But it’s also empowering for me as a technical writer. I feel like I can connect and interaction with project teams remotely.

January 18, 2012 at 6:28 pm

Hallo again Tom

A colleague has just given me some more useful information: You can customise the priority names and add/remove priority codes too. Here’s the documentation: http://confluence.atlassian.com/display/JIRA/Defining+%27Priority%27+Field+Values

Tom Johnson says:

January 21, 2012 at 2:38 pm

Thanks, Sarah. I appreciate the link to the documentation. It turns out this is a global change, so it will be harder to push through. If there’s one request I might have with JIRA, it’s to enable more project-specific customizations that don’t impact the global settings.

Jobin Kuruvilla says:

January 18, 2012 at 7:40 pm

| I have to live with a few compromises in terminology

You can change these too, although it can be a bit painful sometimes. Have a look at https://developer.atlassian.com/display/JIRADEV/Customizing+Text

Tom Johnson says:

January 21, 2012 at 2:36 pm

Thanks for the tip about how to change the terms. Apparently, after checking with my JIRA administrator, making these changes would propagate to the global level, for all JIRA projects, so I may have to live with the generic version.

Susan says:

January 18, 2012 at 10:59 pm

Thank you so much for bringing up the topic! I have asked this question is a few seminars and puzzled the presenter. We publish books and use TFS (Team Foundation Server). Our front matter and back matter is kept in a database and it tracks the status of each edition in three steps (like you) … for sale, in progress, inactive. Our books stay in XML, but we can convert to various outputs (even to Word and back). Our supporting documents have their own databases (media, glossaries, authors) and are supported with version control, too. These DBs talk to our other DBs for sales, royalties, commissions, etc. Our editorial staff is to be commended for stepping into the 21st century, but we haven’t yet convinced them to give up their spreadsheet schedules.

Tom Johnson says:

January 21, 2012 at 2:35 pm

Susan, thanks for adding your experience to the conversation. I haven’t used TFS, but I assume this means you’re working with .NET applications. I couldn’t imagine incorporating the actual content into JIRA. I still use Dropbox for easy file management.

Hezy Asher says:

January 19, 2012 at 8:30 am

At our lab, we use JIRA for tracking projects. As I’m a lone writer, I cannot use it the way you described, yet I find it very helpful in working with the development and QA teams. Nevertheless, the documentation flow via the JIRA had to go through several modifications, and is still far from being perfect, as many times feature changes are not being brought to my knowledge, and the decision whether a certain feature or improvement needs to be documented, when left to the single developer, can lead to either flooding me with internal CRs that do not concern me at all or to keeping me out of the loop (not deliberately, of course) when adding or changing GUI components or other customer-facing features. If anyone has a more positive experience in this regard, I’d be glad to read about it.

Tom Johnson says:

January 21, 2012 at 2:34 pm

It’s great to read the diverse number of ways that writers are using JIRA. I definitely need to get workflows figured out.

I think understanding JIRA (or some other bug tracking tool your company uses) has to be one of the keys to staying informed about a project. Of course this assumes that everyone uses it.

Pablo Varela says:

January 19, 2012 at 9:56 am

Adding cents to the conversation:

* Greenhopper rocks! Definitely consider it for managing issues (assignments), versions (sprints), and so on. Great time saver plus it will give you a burn-down chart to track progress.

* As mentioned by Sarah above, workflows are heavenly. For my team at Intel, we have set workflow “milestones” such as: Content Specification first, then an Alpha version is created, then a Beta version, and so on till completion.

Each of these states is a Jira issue, with an owner, belonging to a component, with a certain fix version, etc. We use Crucible for reviews, Confluence for annotations. The whole bunch. (Thanks Maddox for the great tips on technical writing with Atlassian products!) Of course, we already have all these products set for us. I bet you can easily find alternatives for each you are missing.

* If you decide at one point you want to “Go Atlassian”, the Crucible + Fish Eye combination is a must. It will give you friendly access to your SVN repository. So you will have seamless links between your Jira issues and items committed to your repository, even specific changes.

The drawback here is that Crucible reviews work very well on plain text files (we use this mostly for content specifications and alpha/beta versions of deliverables), is clumsy with SGML/XML/HTML and derivative documents since you get to read all the markup along with the text, and is useless with binary Office documents. Atlassian should really start processing OOXML.

Tom Johnson says:

January 21, 2012 at 2:30 pm

Pablo, thanks for the tip about Crucible and Fish Eye. I hadn’t heard of those, but I’ll check them out. We do have Greenhopper installed and you’re right, it’s very useful. Thanks again or commenting and sharing your insight.

January 19, 2012 at 10:49 am

Hezy – one option in JIRA is to register as a watcher for the features you are documenting, that way you will be notified when the change – the notification can be customised in JIRA so you only receive the notifications you want.

We manage documentation as a separate project within JIRA as we are servicing several development projects, that enables us to create custom workflows, status etc for out documentation tasks which are different from the standard development workflows.

A good tip is to use a plug-in called create-and-link this can be configured to create a documentation task from say a feature, and the great thing is it automatically create a link between the 2 issues, so you can say sign-off of your Feature is dependant on completion of the documentation task, even if its in a different JIRA project

Tom Johnson says:

January 21, 2012 at 2:28 pm

I’ll keep my eye out for the “create and link” plugin for JIRA. I thought by default JIRA allowed you to link to other items, such as to specific that one item is dependent on another, or that one item is a subtask of another.

DiSc says:

January 20, 2012 at 9:27 am

We use Jira in our organization as well, but until now very little documentation was tracked with it: other departments would open tickets that eventually would require documentation, and we would just add our comments and report our activities – but only on behalf of other departments.

Internal tasks, like changing templates, reorganizing the documentation structure, adding a section here or there – would not be tracked in Jira, just in someone’s notebook.

This is changing now and we have our own “documentation”-project in Jira. I think this is a good thing – it makes us more accountable to other departments.

Jira is a very user-friendly ticketing system as far as I can tell, and in general Atlassian software is both good and enjoyable to use.

Tom Johnson says:

January 21, 2012 at 2:26 pm

Diego, it’s interesting that you’re using JIRA to allow other depts to request documentation. We haven’t taken it to that level yet, but it’s neat to see other uses like this.

Barbara Green says:

January 27, 2012 at 5:38 am

Since almost all of our documentation resides in Confluence (the transition is nearly complete), we started using JIRA to track documentation work requests from other departments. In fact, I just requested additional logins this morning from R&D for the Training & Implementation team and some for Support. We have discussed making JIRA available to anyone in the company so that they can enter work requests for IT, Marketing, and Information Design. Our previous system was behind the firewall, which made it difficult for contractors to access. But JIRA (hosted) has been wonderful for communicating with contractors and our Seattle and Phoenix offices, or even accessing from an iPad when on the road. I’m grateful for the tips and can’t wait to try them out on our documentation projects.

Also, we’ve recently started working with Adaptavist on a theming plan for Confluence and learned that they can also customize JIRA for uses beyond issue tickets. I’m excited about this and hope that JIRA soon replaces our clunky, outdated, mostly broken work request system company-wide. Additionally, our documentation team has been testig the use of a JIRA macro to automatically pull resolved issue tickets to release notes within Confluence. What a time-saver this will be! Here’s an example: http://wiki.acstechnologies.com/display/Stratus/Sprint+2011.6+%28Nov.+15-Nov.+29%2C+2011%29

Best Wishes.

Tom Johnson says:

February 2, 2012 at 1:07 am

Barbara, thanks for sharing how you’ve integrated Confluence and JIRA. I am jealous of your setup. I think I would like to move to a system like yours ….

I hadn’t thought of using JIRA for work requests, but it makes sense. Thanks again for commenting.

I'd Rather Be Writing