Jira Image of the Day: Naming Settings for Your Audience

[#1]

Concept Relates To

Application Type	Jira Work Management, Jira Software, Jira Service Management, Jira Core
Deployment Type	Jira Cloud, Jira Server, Jira Data Center

What is shown?

An end user’s view of a workflow (left) and an administrator’s view (right)

Visit: Admin > Issues > Workflows

What can we learn?

Naming in Jira is so important but it often doesn’t get the attention it deserves. I’ll use workflows and custom fields in this example, but having an audience-specific naming strategy applies to every scheme and setting in Jira.

Each Jira scheme and element has different attributes, like a name and a description. For example, workflows have the following attributes:

Workflow Attributes

• Name

• Description

• Association

• Statuses, transitions, properties, and more

Different workflow information is visible to multiple audiences. Some information is visible to end users and some is only visible to admins.

As shown in the screenshot above, a workflow’s name is visible to end users in an issue’s workflow diagram. A workflow’s description is only visible to administrators, however.

Here’s another example showing a custom field.

Custom Field Attributes

• Name

• Description

• Type

• Additional settings like options and default value

• Screen associations, contexts, and more

A custom field’s name and description are visible to both end users and admins. So, it’s important to consider who is consuming the information.

Recommendations

I always try to name elements for the function they support or the problem they solve.

For the end user audience, I try to provide a helpful description or an expected response or format. For example:

Field name: Cost
Description: Please enter the total paid in the format: $0.00.

Field name: Mileage
Description: For miles driven in personal vehicles while traveling. Do not include rental car miles.

Descriptive instructions help the user provide the exact information you aim to collect.

When information is only visible to administrators, however, I use the opportunity to associate a setting with the Jira issue created to track it. (Yes, you should use Jira to manage change in Jira!) For example:

Scheme name: Finance Workflow
Description: Created with AS-123

Now I can reference the Jira issue AS-123 for all the details about why a setting was created, who requested it, and more.

---

Back to intro and image list

[Matt Doar _Adaptavist_]

All good advice. I also find that naming workflows as "XYZ Workflow" and then schemes as "XYZ Workflow Scheme" helps keep from getting confused in large instances. The XYZ part can be a Jira project key or a short indicator of what the thing is for such as "Legal" or "Docs"