Aligning terminology across a product & portfolio

Summary
Cloud Pak for AIOps is a complicated product compounded by the fact that it’s an enterprise software offering among thousands in IBM. Terminology alignment can be a challenging endeavor both inside the product and at higher levels. As the team’s UX content designer, I encountered several challenges with respect to terminology.

Problem & user needs
With any product in a very large organization that has a lot of offerings, you are probably going to run into terminology problems. Are you using terminology consistently (both within a single product and within the portfolio of products)? Are you defining terms accurately and in line with industry standards? Are you using more than one term for the same concept or object? Having inconsistent terminology or using multiple terms to mean the same thing can be confusing for users in both understanding and trying to use your product. This is compounded when users have more than one related product from the same portfolio.

Role
Lead (solo) content designer on Cloud Pak for AIOps and AIOps Insights, working with key stakeholders across the product & portfolio

Key contributions

  • Worked with the AIOps information development (ID) team terminologist to identify inconsistent and problematic terms.

  • Stayed aligned with the larger Cloud Pak Platform team on issues and overlapping terminology across the Paks.

  • Led efforts to assemble the right stakeholders and make decisions on terms usage.

  • Researched industry terminology in similar products and provided recommendations and input to team discussions.

  • Collaborated with design, development, product management (PM), ID, architecture, and wider content teams to discuss and resolve terminology problems.

Outcome & impact

  • Resolution on the set of terms to include in the Cloud Pak for AIOps glossary and verification of alignment with the UI.

  • Consistent usage of terms in our UIs.

  • Alignment with industry standard terminology.

  • Alignment across products in our portfolio, where possible.

  • Ability to quickly recognize when terms might be an issue and require additional vetting.

  • Establishment of a go-to terminology process for term evaluation.

With each different terminology exercise, my skills continue to expand in this area in both recognizing the need for terminology intervention and tackling how to address the issues.

A few highlights

Cloud Pak for AIOps general terms and glossary effort

The Cloud Pak for AIOps product combines capabilities from several existing products with an injection of new functionality. Naturally, this effort surfaced some issues with terminology as concepts were changing and as we became one of the Cloud Pak products. The main problem was terminology mis-alignment. The team was large with about 7 design squads to cover different areas of the product UI. As varying levels of experience and understanding was coming together, someone started an internal terms list to help identify when a term was being used to mean more than one thing, had different definitions across areas, or was a new term to our product. The list had gotten quite large and there was clear disagreement in some areas. As the UX content designer on the team I was given the task of figuring out how we could come up with one list of agreed upon terms and definitions.

I started syncing with the ID team and discovered they had a terminologist, Steve Schwartz, who was willing to work with me. We met and hit it off immediately. In addition to terminology work, Steve had been the lead writer for one of the products that was merging into Cloud Pak for AIOps so he brought a wealth of technical knowledge and background. We formed a plan to take the internal terms list and review everything to determine where the main sticking points were. We compared terms against our IBM Terminology glossary and industry standards, verifying definitions and reworking things like definition structure to make them parallel.

Once we had a cleaned up list, we worked to identify key stakeholders from across the teams and began a series of review meetings. We explained our mission and started getting feedback. The calls were tough because we had so many important people invited that not everyone could make it. We had several reviews over many weeks and continued refining definitions and whittling down our list of contentious terms. During this time, Steve was also leading a cross Cloud Pak terminology workstream and we had to also ensure that our terms were aligned at the Cloud Pak level. There were nine Cloud Paks but only a few in contention for overlapping terminology. After much review and refinement, we published the first glossary of fully reviewed and vetted terms in the Cloud Pak for AIOps documentation in the spring of 2021.

Glossary worksheet for determining the status of terms as we vetted and settled on which to keep:

Automation terminology

Following the publication of our glossary I began attending calls for the Automation Base Pak IA & Taxonomy consistency work stream, which was created to align various terminology efforts across Cloud Pak teams that were part of the Automation platform. The aim was to create a comprehensive terms list across products. This list would include definitions and how the term was being used within each Pak with a goal of flagging any terms that were not consistent. The aim was to publish one single terminology list that all teams could reference.

Under the umbrella of this work group, another terminology challenge arose when our team started looking to change the term “policies" in Cloud Pak for AIOps. Some of the other Paks were using “workflows” and “automations” and there was a lot of overlap of terms in this space both within and outside of products. I started digging in to try and understand whether this was simply a name change or if there were two different concepts we were trying to explain. I organized several meetings with our cross discipline (xBox) teams and wider affected Pak teams. Our UX design lead facilitated an OOUX (Object Oriented UX) workshop to try and help us align.

After synthesizing the outcomes from several meetings and getting input from our user researcher who had done testing on terminology, we ultimately took a poll of all internal stake holders to make our initial decision as we were running out of time before the release date.

Trying to figure out our definitions for terms related to automation tasks:

Event-related terms across the AIOps portfolio

Following the deep dive on automation terms came an effort to align events terminology across products in our AIOps portfolio. We had similar concepts around events, alerts, notifications, and incidents, but were using different terms across three products. This was partially due to Instana’s acquisition status. As the teams were moving towards better integration among the products so that potential customers could gain additional functionality with ease, it became apparent that we needed some terminology work.

I got involved in this effort after one of our lead architects starting trying to align stakeholders from the different teams. He worked on identifying the key terms, listing definitions, and highlighting major areas of contention. I focused on looking at the user experiences with respect to the terms across the products and mapped out user journeys to see where we had discrepancies not only in terminology but how the objects were represented in the UI and how that would impact our discussions and alignment plan. I also pulled in my terminology partner in crime, Steve, to look at the terms with me as he was working part time on the documentation team for one of the products. We did a comprehensive review of industry terminology for products in a similar space to help inform our direction.

We met weekly with reps from each team to discuss our findings and develop a plan. We ultimately decided to align the event terms to the usage in Cloud Pak for AIOps. One of the products, Instana, had an existing customer base so they needed to vet any terminology changes with their users which would take a little more time but was definitely the right direction.

Evalutating event-related terms across our products:

Reviewing industry terminology to verify alignment: