Now that I’ve been at Atlassian for almost a year I’m truly in awe of how many different kinds of organizations use JIRA to help teams of people deliver their visions. While the specifics of each implementation differ, each customer uses JIRA to track information so that everyone in the team can stay on the same page. Let’s learn how to present and organize information in JIRA so we can optimize how the team uses information.
Defining issue types, fields, and workflows
How does JIRA present and store information? There are three main areas to explore: issue types, fields, and workflows.
- Issue Types – Issue types are entities that mirror real world objects. Software teams will often use issue types like bug, task, and user story. If JIRA is used for asset management, each asset could be its own issue type. Issue types are the key structural elements in your organization you want to track.
- Fields – Fields track attributes surrounding each issue type. Bugs usually have fields like summary, description, fix version, and component to describe the area of software where the bug surfaces. If JIRA is tracking computer inventory, fields might be manufacturer, memory size, disk storage, CPU speed, etc. Fields are always data about the object that represents the issue type.
- Workflow – Workflow is the lifecycle of the object represented by the issue type. Bugs are found, reviewed, fixed, verified, and closed by several members of the team. Computer hardware is ordered, purchased, put into service, and then eventually retired. Workflow describes what the issue type does.
Fields allow teams to track data individually so that it’s easy to search and track later. When organizations first adopt JIRA there’s a strong temptation to add a whole bunch of fields like a kid in a candy store. Like many things in life, too much of a good thing can be bad.
In a rollout of JIRA several years ago, I interviewed many different stakeholders at the company for what data they wanted to track on one of our issue types. The stakeholders spanned several areas of the business and had key wants for the new system. What did I find out? The business wanted to track over 60 different fields on this one particular issue type. To put that into perspective, the average tax return in the United States has between 20 and 80 different fields. We were asking each user to put the same amount of effort into putting an issue into JIRA as it was required to file taxes!
We were victims of field-itis.
Field-itis is a common condition in many JIRA instances when the team asks for too much information from its user base. When someone requests a field, they tend not to realize that their field has a cost; every time a new field is added into JIRA it becomes harder for users to create issues. No one likes to see a giant form with lots of cryptic terms in it. How do you know you’re struggling from field-itis? Let’s center around three important questions:
- Are people not filling out all of the needed information when creating issues?
- Do people not submit issues because it’s too much work?
- Are certain fields collecting bogus information because end users don’t understand them?
8 cures for common field-itis
1. Ensure the field meaningfully impacts the business
JIRA administrators, when someone asks you to add a field into JIRA, I’d encourage you to always ask the following questions:
- What is the business value of this field? In other words, how does knowing this information meaningfully impact how you do your job?
- What is required of the end user to submit this information? How long does it take a user to reliably collect and submit the information correctly? Is there any way to automate capturing that information?
- When in the issue lifecycle do you need this information?
Every field has a cost. Users have to:
- Understand what the field is
- Enter initial data
- Update it as its value changes over time
For fields to be useful they need to be filled out and current. When the system becomes cumbersome, users no longer enter quality data. Field rot then sets in as the data is no longer dependable. Ensure each and every field is legitimately needed.
2. Order fields on screens
By default, JIRA adds new fields to the bottom of the screen. When a JIRA administrator initially builds a screen, all the fields are in a logical order for that application. As the team needs extra fields, take the time to add them to the right place on the right screen in JIRA. Doing so will optimize the data entry experience for your end users? Forms should have flow. Each new field should bring a user closer to completion. Let’s look at two forms (click to expand):
While the first one captures all the right data, the second screen has flow. Ask a few people who use each screen on a regular basis if the flow is right. Tuning flow will help users get better data into JIRA making for a more optimized team.
3. Fill out the field description
Every custom field in JIRA has an option to give a description of that field. Make use of that description so that users can learn what information is needed in that field. I’d keep the description short so that the overall screen remains compact. You can use HTML in field descriptions so that it’s easy to link off to more extensive documentation. For example, let’s look at a sample description for a field called build number.
The build number is the current version of software. See the build docs for how to find the build number.
Educating your users goes a long way to making everyone more efficient on the team.
4. Respect the required option
If you take one piece of advice from me in this post, make it this one: Use the required attribute carefully. There is a strong temptation to make fields required. You need the data right? So why not ensure my users enter it? Well, if your users don’t know what to enter they may give you bad data – and bad data is worse than no data. It’s hard to get rid of bad data in searches and makes reporting a nightmare.
If you must require a field:
- Have a way to say “I don’t know”
- Give a field description (see step 3 again)
People in general want to do the right thing. If team members are artificially blocked they will often go around the gates to be heard. Teach people how to be complete rather than making issue submission difficult.
5. Remove unnecessary fields
Teams often change, and what was important a year ago may not be so important now. I found many times the user will come to me saying, “I absolutely need this field!”, then a couple of months go by and the team doesn’t use the field in the way the requester originally intended. In JIRA you can easily search to see how many issues use a particular field. Let’s say we added a field called build number to the issue type bug. We can then run two queries to see the percent utilization of that field.
Bugs that don’t have a build number
type = bug and "Build Number" is empty and created > "2013-02-01"
Bugs that have a build number
type = bug and "Build Number" is not empty and created > "2013-02-01"
I added the clause created > “2013-02-01” so that I exclude issues created before I added that field. What do I do If I don’t have that data? Run the this query:
type = bug and "Build Number" is not empty and created > "2013-02-01"
ORDER BY created ASC
You can then use the first issue’s created date.
We can then compare the number of bugs that have a build number with the ones that don’t. If the team isn’t effectively utilizing the build number field they have a decision to make: Do they require the field?
If they do require the field, then running this type of query becomes much harder to do (see step 4).
6. Spread out data entry
In many organizations a collection of data around the particular issue type happens throughout the workflow. For example, a bug requires things like summary and description up front. It’s not until the bug gets fixed that it needs a resolution and optionally a code reviewer.
With JIRA, administrators can customize screens to make data entry a more natural experience. Users reporting issues only see the fields relevant to them. When an engineer reviews an issue only the fields that are relevant for that operation appear. That way, no one is overwhelmed with all the fields at once.
In JIRA, the issue detail view has all the fields listed. The product team has taken great strides in organizing how that information is presented to you, the user. We’ve got clear headings for issue details involving people, dates, descriptions easy to find the details you’re looking for.
7. Scope each field
When administrators create custom fields, they have the option to limit them to certain projects or make them available to all projects. Using project contexts to limit where custom fields show up makes it easier for everyone. Forms that only have what’s necessary makes everyone more efficient.
8. Automate all the things
I’ve saved the best tip for last! Automation allows you to collect data efficiently and correctly. JIRA offers two easy ways to create great issues with rich data support.
JIRA Capture is a browser-based tool that makes it easy to screenshot applications and annotate them for additional detail. For web applications, JIRA Capture can instrument the application’s DOM and record application specific data right to JIRA.
JIRA also has a flexible REST API that makes it easy for external applications to create issues and populate custom fields. Developers have easy access to a wealth of information that can be difficult or tedious for users to manual enter. Empower your engineers to help them get better issues by connecting JIRA to your application.
With JIRA Capture or with the REST API, engineers can then get high-fidelity detail about reported issues without burdening users with large amounts of manual work.
Maximizing fields in JIRA 6.1
Fields are an integral part of JIRA and makes the JIRA platform work in so many organizations. As JIRA administrators, one of our key contributions is helping people understand best practices for using JIRA. Using fields for what they’re great for and minimizing the downsides helps everyone be more successful with JIRA.
With JIRA 6.1 we’ve made it easy to add fields right from the issue detail screen.
We’ve also added a field gallery so administrators can see a visual representation of the field before they add it.
JIRA makes it easy to build field configurations to share across many projects to make maintenance easy. JIRA notifies the administrator if a new field will impact other projects. The administrator can then decide how he or she wants to proceed.
In addition, many custom field types are available on the marketplace for download into your JIRA installation.
Want to learn more about what’s great in JIRA 6.1? Check out the JIRA 6.1 announcement blog and accelerate change in your organization today!