< Back to 2017 samples

Procedure for platform-level terminology decisions

The Content Design team gets many requests to help clarify and define terminology across all of the product family and broader Atlassian content. The following is a living document that outlines a working process for making terminology decisions quickly, with confidence and vetting from the appropriate stakeholders.

While terminology decisions don't always fit neatly into this format, you can use the following approaches to help push through a terminology decision and/or recommendation in a timely manner.

The process in a nutshell

Here's the short version (but you should totally read on for more details):

1. Define the problem.
2. Identify decision makers and stakeholders.
3. Provide due dates for investigations and comments.
4. Collect data, if needed.
5. Update the glossary.
6. Communicate the decision.

1. Define the problem

Terminology decisions should be a simple matter of sense checking problematic or conflicting word usages. Sense checks can quickly derail into conversations about scope, tangential terminology, and implementation.

Up front, you should restrict yourself to making a scoped and limited terminology decision. You're not trying to reinvent the entire Atlassian glossary, or fix deeply-rooted historical problems.

To avoid derailing the decision at hand, first define the problem clearly. You may find yourself in between product and platform managers and triads. This is OK. Speak to as many people as you need to clearly understand and articulate the decision that needs to be made.

Questions to ask:

• Can you define the problem in one sentence?
• Talk to me like I'm a new hire. What background information do I need to investigate this problem?
• Is this a platform problem or is it a product problem? Does it affect all products equally? Will it affect multiple products in the future?

Draft a clear problem statement. It's a handy tool to have when you talk to stakeholders. Use it to help prevent derailing the conversation and focus on the decision that needs to be made right now.

An example

The Atlassian Marketplace made the decision to make their terminology consistent for extensions, addons, integrations, plugins, etc., calling them all simply "apps". Our product teams and product marketing materials describe Atlassian-built software as "applications" and various other terms. In some parts of the UI, users see both Marketplace "apps" alongside Atlassian "applications". We want to make our product-facing terminology consistent and intutitive to our users.

From a recent [decision], the problem is outlined as such:

• We are inconsistent in how we reference things developed by Atlassian (e.g. Jira) both online and in product.
• We are inconsistent in how we reference things that you can install in Atlassian Product (e.g. Marketplace apps) both online and in product.

How might we clarify and validate what term resonates with our users in our products?

How might we investigate the impact and scope of any prospective change to our products?

2. Identify decision makers and stakeholders

The Content Design team should own most terminology decisions. That said, terminology may have a product and engineering cost associated with what decision is made. For this reason, The Content Design team is considered a driver of terminology decisions. Approval usually comes from the broader team. And, the products have a large stake in any outcomes from a terminology change.

Decisions that are broad-sweeping may require a DACI. Decisions that are compartmental, new, or have a low impact may require a simple "go ahead".

To help determine whether or not to proceed with a full-blown DACI, weigh the decision's impact and urgency:

Definitions of impact and urgency:

Widespread – the term is used across all Atlassian products and online properties. For example "issue".

Large – the term is used across some or most Atlassian products and some or most online properties. For example, "boards" (not used in Jira Service Desk, Stride, etc.).

Limited – The term is used across a limited set of Atlassian products and only some online properties. For example, "repository".

Localized – The term is used in one or two Atlassian products and a limited set of online properties. For example, "queues" (only used in Jira Service Desk).

Critical – Multiple product, marketing, and communications teams are blocked by the decision.

High – Some product, marketing, or communications teams are blocked by the decision.

Medium – Future roadmapped work will be affected by the decision.

Low – The decision does not affect current or future roadmaps.

After determining how to proceed, you should identify stakeholders to involve in the decision-making process. The Content Design team has a standard triad for terminology decisions, and a comprehensive list of potential stakeholders you may need to involve. Read about how to run the DACI play in the Atlassian playbook.

Chat with the Content Design terminology triad. Present the problem definition and they can help determine who the most relevant stakeholders are before you continue.

Provide due dates for investigations and comments

To keep the decision on track, outline major milestones in the decision-making process. Communicate these to your stakeholders and decision makers. Make it clear when comment periods are open and when you will provide data to help them make their decisions.

Depending on the problem's urgency, holidays and other factors, large and widespread terminology decisions can take more time than you anticipate. Timeboxing comment periods is the best way to keep the decision moving and an end date in sight. Operate under a "speak now or forever hold your peace" mentality. As the driver, it's up to you to hold stakeholders and decision-makers accountable.

For example:

4. Collect data to help decision makers

The most important function in this process is collecting data to help inform the decision. This matters regardless of if you're making a low-impact gut decision or presenting detailed findings to a seemingly endless list of informed parties on a DACI.

The most useful pieces of data to collect are:

• investigations into the scope of the problem
• brief competitor and market investigations
• summaries of previous decisions and/or discussions related to the problem
• surveys or user tests

Conduct a terminology audit

Audits help decision makers understand the implications of a terminology change. If you're dealing with a widespread or large terminology change, reach out to the content designers on the effected products and ask them to carry out an investigation into where a term exists in their interfaces, support materials, online properties or other sources.

It may seem like outside help could slow down the decision-making process, but many hands make for light work. You'll save yourself time investigating the scope of a problem and get a much better overview of the impact.

Conduct a competitor and market audit

Seeing what other companies are doing can help you investigate alternative terms or get better clarity on how the tech community views certain terminology. Even brief looks into major competitors can help broaden your investigations and open up options for decision makers.

Conduct a brief literature review

Most terminology decisions have a long storied past at Atlassian and EAC is it's keeper. Take the time to find as much information about previous decisions, events and timelines for how a term has been viewed internally over the years.

Summaries of these documents help decision makers understand how we arrived at the problem you're trying to solve. Some tips for writing summaries of previous investigations:

• Be as objective as possible and report only the facts. You can't undo the past. Think how you would want your work in a decision to be discussed at a later date.
• Use direct quotes when possible and link to the source material.
• Provide timelines and structure your review chronologically to help highlight gaps or quickfire decisions.
• Avoid recommendations or reflections. You're providing data for decision making at this stage. You're not making a decision.

Conduct surveys or user tests

Audits and literature reviews do a great job of informing decision makers of how terms are used at Atlassian. But, this shouldn't be your main focus. To provide great, intuitive experiences, we need to understand how real people outside of Atlassian think about certain terms.

A few, quick signal tests can help you understand the connotations of certain terms. The quickest and easiest are simple surveys. Here's two that can be conducted quickly:

1. Define this term. Create a survey that asks respondents to define terms related to your problem definition. Test them on synonyms and alternative wording to see what associations people generally carry with a given term.
2. Provide a term. Create a survey that asks respondents to provide a term for a given definition. Finding definitions for terms related to the problem can be tricky. Atlassian's official dictionary is Merriam-Webster's. You may search for more relevant definitions in Microsoft's Language Portal, your Mac's Dictionary app, Wikipedia, existing legal documentation, or internal reference guides. You may create your own if you know the nuance you want to tease out.

Generally, it's a good idea to segment these surveys by audience. Your decision may be more impactful for third-party developers, for example, than new or existing users. Segmenting survey data gives more detailed information to decision makers and helps them understand the impact of terminology changes.

If you find that two closely related terms are understood by all and are still having trouble collecting data that differentiates terms, you might consider sending out a preference survey. Create a survey that uses fill-in-the-blank questions and asks respondents to choose between multiple choice options for their preferred term.

Write definition, examples and update the glossary

Draft a definition for the term, include examples and submit a request to update the glossary to the Content Standards team.

Communicate the decision

While deciders and approvers will hopefully understand the decision and why it was made, communicating it to a wider audience helps alleviate future discussions. This is especially true in widespread or large terminology decisions.

Write a blog that:

• summarizes the problem and the decision made
• summarizes the data collected and used to make the decision
• outlines the options discussed by deciders (including pros and cons of each)
• provides links to related DACIs, surveys and other artifacts
• thanks everyone involved in making the decision

That's it!

If you do everything outlined here, you'll have the correct buy-in from the most appropriate stakeholders and, more importantly, real people. Don't be afraid of the outcomes or implementation details. You've done due diligence and an incredibly thorough job. Go get a bubble tea and relax.