Why Technical Writers Should Use Jira
Or any other ticket tracking system.
How does your team track documentation requests?
Email threads? Spreadsheets? Hastily scrawled post-it notes?
Hopefully, it's not the latter. At any one time, I’m usually keeping track of 20–30 different requests for various products or initiatives. I’m busy, but I’m not stressed. That’s because I know where everything is, what I need to be doing, and how much time it will take me.
And, I use Jira.
What is Jira?
Jira is a ticket tracking tool primarily used by software developers in an agile environment. It was originally a bug tracking tool but has since evolved into a project management tool that covers a variety of use cases.
So why should technical writers care about Jira?
- Your developers are probably already using it.
- You can track (almost) anything.
- You can quickly visualize your progress.
- You can easily update your stakeholders.
- You can simplify time tracking.
Let’s jump right in.
1. Your Developers Are Probably Already Using It
According to Atlassian (the makers of Jira), more than 65,000 companies and teams use Jira to track issues and product deliverables. If your team already uses Jira for software tracking, then your information source is Jira.
Using Jira to track writing deliverables is especially beneficial because your knowledge of Jira will help when hunting for information in engineering projects. It also makes it much easier to stay informed of issues and bugs that need to be documented.
💡 Tip: With agile teams that may struggle to integrate documentation with development sprints, see if you can get documentation added as acceptance criteria for relevant stories. It’s a small change that gives you just a little more visibility, and also helps developers plan for the extra time they’ll need to spend reviewing your documentation.
Also worthwhile to note is that Jira lets you link tickets, so you can mark your documentation story as dependent on an engineering story. That dependency will show up on an engineering ticket, giving you visibility.
2. You Can Track (Almost) Anything
While most of its features were developed with software development in mind, Jira isn’t limited to bug tracking.
For our use, each story in Jira is an article we need to write or update. We don’t include ideas for future articles as stories, those are tracked elsewhere. Everything we track on Jira is visible and assigned to a writer.
We mainly use Jira as a kanban board, which provides an overview of tasks in columns based on status, such as “In Progress” or “Review”.
Our project is split into two kanban boards:
- To track documentation for continuous deployments, scheduled releases, or team projects.
- To track documentation support tickets, which are requests for updates or changes to published help documentation. A filter automatically converts emails to our docs support address into Jira tickets.
💡 Tip: If you only do one thing, centralize your tracking of requests for documentation updates. Nobody wants to be wrangling information from email, Hangouts, Slack, Jira, and passing requests in meetings.
3. You Can Quickly Visualize Your Progress
One of my favorite things about tracking all of my documentation in one place is that I can actually see my progress. There are multiple ways to get a picture of what’s going on.
You can see progress broadly, from a board:
Or granularly, from an epic:
You can even view reports, such as this pie chart of all issues assigned to me:
Clicking on an area in this pie chart opens up a Jira filter of all those tickets. So if I click on the green slice, I’ll be able to scroll through all my tickets that are waiting for review. Handy for following up on review with SMEs en masse.
4. You Can Easily Update Stakeholders
This one is a blend of keeping everyone updated, and keeping yourself sane. I make extensive use of the commenting feature on Jira, which is to say I frequently comment on my own stories with updates.
This looks a little something like this:
8/13 Update:
Met with the review team to review the current list of software updates. All outstanding tickets were reviewed.
• Bob will be adding more tickets in the coming sprint.
• Next week’s meeting is canceled, as Bob will be OOF all week.
• Follow-up meeting tentatively scheduled for Thursday, 8/27.
By keeping your documentation stories updated, you’ll almost never need to field questions from stakeholders asking about the status of something. As long as your stakeholders are watching your ticket, they’ll always be in the know.
5. You Can Simplify Time Tracking
One thing that can be difficult to quantify is the amount of time it will take to document something. When I take on a new project, most of my time spent at the outset is on research and planning — meetings with SMEs, checking for existing documentation, or reading up on engineering stories.
That time is variable depending on my familiarity with the subject matter and the scope of the documentation request.
That is why it's important to track time on your stories. Each time you log time on a story in Jira, you can add a comment to note what you were working on. Here’s what I consider “trackable” time:
- Research
- Meetings (directly related to the document, such as initial planning, knowledge transfers, and review meetings)
- Writing
- Editing
- Publishing
Once you get into the habit of tracking time consistently, you can analyze the time you’re spending on each stage of the writing process to determine areas that may need improvement.
If past is precedent, time tracking also provides you with a baseline of how long a particular assignment may take you in the future. For example, you can determine that documenting exhaustive steps to configure a new feature takes you 3 days, but documenting a workaround takes you 3 hours.
Time tracking is crucial to capacity planning. You have no way of knowing how many assignments you can handle if you don’t know how much time they will require.
TL;DR
Why should you use a ticket tracking system as a technical writer? Because there aren’t enough post-it notes in the world.
