Intro to Jira as a Research Manager

This documentation focuses specifically on the best Jira practices for research managers. For more general information on Jira hygiene and best practices, click here. As research managers, we must ensure that the product team and contractors clearly understand the tasks that need to be performed each week to meet project deadlines. Jira acts as our internal project communication hub, providing the transparency needed for everyone at Gradient Metrics to have insights into the status of issues and the overall project.

Part of the project startup workflow includes creating and adding a project roadmap to Jira. Roadmapping is an excellent opportunity to engage in the Gradient principle of “Thinking backward.” Although you might not be able to identify all the issues needed for the entire project, you should be able to create many of the core issues.

First, create issues based on your previous experiences with similar projects. For inspiration, you can review past projects in Jira and explore all the issues that were created. Next, consider what is unique to the specific project you’re working on. For example, the data collection might be more involved, or there might be an added synthesis element. Whatever the specifics, create an issue for it now to ensure it doesn’t get overlooked. Since roadmapping typically occurs right after project kickoff meetings, you likely have the best understanding of the overarching tasks needed for the project, so it’s important to record them in Jira sooner rather than later.

What is not needed during roadmapping:

1. You do not need to provide a full spec for every issue you create at this time. Not only is it not expected, but it is also likely not possible since the project will evolve as you move forward. Feel free to drop a “TBD” in the issue description or add some basics that you don’t want to forget (such details should also be recorded in the project playbook!).
2. If you will not be the lead on the issue, you do not need to assign it to a team member immediately. It’s fine to wait until the week before they need to start working on it to assign the issue—more on this in the next section.

When you create new projects in Jira, you’ll also need to create releases. Releases act as folders for all the major phases of the research. Each issue you create must be assigned to a release. Projects typically share a similar set of releases, such as Survey Design, Data Collection, Analysis, and Synthesis. However, your project may have unique elements requiring different releases. When planning your roadmap, take a high-level perspective to best organize your issues into appropriate releases. This approach helps ensure that your project stays organized and that progress can be easily tracked throughout its various stages.

Before the start of each sprint, review your project timelines and assess what tasks will need to be completed to keep the project on track. Once you have a clear idea of the tasks that need to be finished by the end of the next sprint, ensure that each issue created during the roadmapping phase is assigned to the appropriate team member, including yourself, and has a detailed spec. New tasks have likely surfaced since the roadmapping phase, so be sure to create new issues for yourself and other team members as needed.

At times, you’ll need to assign issues to the “contractor” account. These issues typically do not call for specs in Jira, as our contractors do not have access to the platform. These issues are meant to 1) help us keep track of how many hours we dedicate to a project and 2) show the other team members the status of projects. As project lead and the person who is likely in contact with the contractors performing the tasks, it’s your responsibility to update the progress of contractor issues as tasks move through their stages of completion.

Almost every client deliverable must be reviewed by another team member before it goes out the door. For quick reviews you estimate will take less than half an hour, communicate with a team member that you’d like a review and add a “review” label to the issue. When communicating with team members, be sure to tell them when you expect to have the deliverable ready for their review and when you need to send it to the client.

For lengthier reviews, it’s best to create a specific Jira issue for the team member you’ve asked to review your deliverable to ensure they have story points reserved for the task. Be sure to keep your team members up-to-date on your expected timelines!

While spec’ing an issue for yourself may seem tedious, it’s a wonderful opportunity to organize your thoughts before starting a task. It can be a great time saver as it helps you continue to think backward. It’s best to think of specs for yourself as an initial outline of the final product you hope to achieve.

Another reason we spec issues for ourselves is to gain insights from others. Tagging other team members on Jira issues with questions is acceptable and encouraged.

Lastly, it’s important to thoroughly spec an issue, even if you expect to be the only person working on it. You might miss work due to an emergency, or other tasks might take precedence in your sprint, requiring you to delegate the task to someone else.

Since we work remotely, proper spec writing is extremely important to ensure that tasks get done correctly and efficiently. At Gradient, we follow the principle of “over-communication,” which essentially means that a spec can’t be too long or have too many details. However, this also means organizing your spec becomes extremely important—hence, we have some important best practices.

When spec’ing issues for others, you should assume they have little insight into the project or at least the specific task you’ve assigned them. Therefore, it’s great to start specs by setting the context. To set the context, include details like why the issue was created and how the end result will be utilized. Doing so also allows the other team members to suggest a different approach or solution.

Using headlines is a great way to organize your thoughts. The longer the spec, the more headlines you should have.

Formatting is another great way to organize your thoughts and requests in a spec. We highly encourage the use of bullet points. Bolding and underlining important elements is a great way to ensure they don’t get lost in a longer spec. You’ll develop your own style of writing specs, but for many on the Gradient team, bolding and underlining are used for questions embedded in long specs. Such use of aesthetics helps differentiate the instructions you’re outlining and questions you may have for your team members.

Writing complex instructions or ideas can be challenging, even for the best writers. It’s helpful to include examples to convey complex ideas. Providing examples is particularly helpful when describing plots for the product team. Using plots from past projects, basic ones you’ve created in Google Sheets, or even hand-drawn ones can provide a helpful starting point for describing the end product you’re hoping to achieve.

Every time you comment on an issue, it’s best practice to tag the person the comment is intended for so they receive a notification. It is also common practice to tag team members that should have eyes on your spec or comment, even if a reply from them is unnecessary.

If you’re tagging multiple team members and asking them different questions, consider placing each question on a separate line to make it clearer.