Innovation requires words: Creating a product glossary

Daniel Moul
Last updated: April 26, 2012
Build basis: Rational Requirements Composer, Rational DOORS Next Generation

Note: You can experience the term look-up rich hovers described below by reading this article in the Requirements Management self host.

A true story of innovation

Some years ago Rational executives made a decision to invest in developing a next-generation, collaborative requirements definition and management product.  This would be part of an emerging application lifecycle management (ALM) solution built on Jazz integration principles and technologies.  As part of this innovation process we, the requirements product team, needed to invent concepts and find words to represent them.  This is the story of our journey to create and evolve our terminology as a multidisciplinary team: first to deliver IBM Rational Requirements Composer, and more recently to extend that product to address the needs of complex systems development in IBM Rational DOORS Next Generation.

I have been part of the product team that brought each release of Rational Requirements Composer to market, starting with the first release in 2008. My “home” is in the product management team. I have taken a special interest in defining and refining these concepts – so much so that I initiated and led the RM terminology working group. In this article I explain how over time we polished process that we use to define terms, and how the integrated glossary facilities in Rational Requirements Composer and Rational DOORS Next Generation make the job easier for the team that creates terms and the larger product group that uses them.

But first a few thoughts on why glossaries matter.

Glossaries for product teams

In projects where innovation is taking place, new concepts and possibilities are in the air. Concepts evolve as the team dreams, discusses, designs, and delivers working code throughout the project duration. New product behaviors and characteristics emerge and change as the team receives feedback and learns more about what is really needed. During this time of creative ferment it is difficult to create a common understanding of new concepts in the minds of the whole project team and key stakeholders. It can be hard to talk about new ideas if you do not have good words for them. And team members and customers who come along later also need an on-ramp to these unique capabilities and concepts. Glossaries are collections of terms that define these concepts.

Glossaries also demystify acronyms. Project teams often work in a sea of alphabet soup: what seems like a million acronyms and a language that is unintelligible to newcomers.

Many project teams include glossaries among their requirements artifacts because (1) the development of terminology requires a process that is very like requirements definition; and (2) a team that is working on requirements needs a good glossary so that members can communicate well, write good requirements, and agree on them. Without a glossary, misconceptions and miscommunication occur, resulting in errors, frustration, and unnecessary rework.

Good glossaries indicate which terms are preferred, which are not, and which should be used with caution. Glossaries are living collections of terms that reflect the needs of teams and their stakeholder communities. Glossaries evolve as related concepts evolve. The project team needs a small dose of leadership and process to make this happen. Like other project artifacts, glossaries are created by a group for a larger community.

• To make clear and productive communication possible among team members
• To highlight which concepts are not well understood or expressed
• To bring the right people, perspectives, and skills to the process of defining terms
• To make the concepts and the product that the project team is creating accessible and comprehensible to buyers and end users

The requirements management glossary

This article explains how the Rational requirements management (RM) product team created and continues to evolve the terminology for our RM products, and how we use Rational Requirements Composer to do so. Throughout the article I refer to real artifacts that the team created in the course of our work. You can explore these artifacts on our public self host on jazz.net.

You might want to start with the Glossary view.

The Glossary view in the RM self host on jazz.net

Another good place to start is the 312: RM self host on Jazz.net: Guide for Visitors.

The RM self host Guide for Visitors on jazz.net

The business challenge

Like many teams, the Rational RM product team is distributed around the world: in the USA, Canada, the UK, Mexico, and India.  The team includes many job roles: product management, development, user experience, user assistance (documentation and education), system test, and project management.  We follow an agile-at-scale development process that includes making high-level feature commitments to the business early in a project, and then exploring, defining in detail, and developing these features in sprints. At the end of each sprint, working code is available.  Many of these end-of-sprint milestones are available on jazz.net. You can download and install them yourself.

While we were developing Rational Requirements Composer version 1.0 in 2007 and 2008, we created a group to determine the terminology for the key concepts in our new product.  In RRC version 1.0 we delivered an integrated glossary facility; however, because it was not ready early enough for us to use, we put the terms on a wiki. The documentation team led the effort; it was their mission to take the concepts that product management and development dreamed up and express them clearly for customers and end users. As we reached consensus on terms, the developers, testers, and the documentation team adopted them in the course of their work. The effort was fairly informal and modest in scope. Even so, we found an important benefit in that the product team used the terms to communicate more clearly with one another as we designed and developed the product capabilities.

The initial glossary lived on a wiki page

Our needs in the V2 and V3 release cycles continued to be modest, and so we did not make an effort to create an organizational framework or evolve our glossary.  Terms were defined in concept documents and requirements artifacts, and they were searchable in the RM repository.  However, we did not consolidate the terms into a proper glossary or review them in a systematic way.

By the time we came to the 2012 release cycle, it was clear we needed to invest in a good glossary and a good glossary development process.  More people in more locations were part of the team. Also, we launched the DOORS Next Generation initiative, in which we are extending Rational Requirements Composer technology to address the RM needs in development of manufactured products and other complex systems. We knew that we needed to be deliberate in evolving the concepts and terminology that are familiar to users of Rational DOORS, Rational Requirements Composer, and Rational RequisitePro. We also knew that we would be introducing new concepts related to modules and the reuse of requirements in modules. We knew that good terminology would make a big difference between the tools being relatively intuitive to grasp or seeming very complicated.

Setting frameworks: The terminology working group

To lay the foundation for developing a good glossary we created organizational and informational frameworks. We formed a terminology working group, which had representation from various team disciplines: product management, user assistance, user experience, development, and architecture. We created a charter and process (1555: Terminology Working Group – Charter and Process) and agreed about how to work together, where to put information, and what to value: "imperfect decisions now rather than perfect decisions later." We met weekly for months during the early sprints. When the workload subsided, we reduced our meeting frequency.

A portion of the charter

Information architecture

As part of developing the charter, the terminology group defined an initial information architecture:

• Artifacts: Terms and term discussion documents.
• Types: Terms and supporting docs.  Supporting docs were used because they already existed in the type system, and they were close enough to what the group needed.
• Folders: A top-level Glossary and Terms folder that contains the terms, with sub-directories for term discussions and charter or project management artifacts.
• Views: One view of the glossary and one view of the term discussion documents. Each view has various attributes displayed in columns.
• Tags: None at first. Tags are easy to create as needed.

The folder hierarchy

Tags for filtering and grouping

As we discovered what we really needed and what seemed to worked best, we refined our information architecture. In particular, we introduced tags to temporarily group or filter information.

Tags in use

We agreed to use these tags, which we continue to use:

• to-discuss: Identifies topics and terms for the group to discuss
• priority: Indicates terms to triage
• deletethis: Indicates terms to delete
• term_DB: Indicates terms that already in or added to the IBM Terminology database
• Various scope tags that indicate which terms go together and which terms must be discussed with the wider Collaborative Lifecycle Management team.

We also use status attributes to indicate various states of approval for terms.

By opening the Terminology Working Group view and applying the "to-discuss" tag, we can immediately see which term discussions need to be scheduled for specific meetings.

Terminology working group view filtered by “to-discuss”

From concepts to defined terms

A new concept is first captured in a term discussion document. We debate potential terms and record the strengths and weaknesses of the alternatives.

A term discussion doc

As these discussions progress to the point when terms can be chosen, we create term artifacts and link them with Satisfied By relationships. A term discussion doc is satisfied by one or more terms, and a term satisfies one or more term discussion docs. These links provide two benefits:

• Group members can navigate to background information when they evaluate the definition of a term. They can also reach the current definition when they review a term discussion doc.
• Group members can see where information is missing in the system. In particular, we can spot which topics do not have terms. The links enable a kind of coverage analysis.

Missing links make terms that are missing visible

After the author feels confident about the definition, and typically after some members of the group view and comment on the term, the term is moved to the Under Review state.

In threaded group conversations, team members ask questions and make suggestions that are visible to the whole team.

Threaded, contextual conversation

Each time someone replies to a thread, an email is sent to specified recipients. The discussions are also displayed in the Comments widget on the project dashboard, so that people who are not part of the thread can follow or join the conversation

Close-up of threaded comment

Agenda, notes, and actions

Until recently I was the leader of the terminology working group. I created agenda documents in Rational Requirements Composer and then emailed the team before and after meetings. These emails included links to the artifacts that are relevant for the topics on the agenda. In the agenda, I linked to each term discussion doc and embedded each term definition.  By embedding rather than copying terms the latest definitions were visible in the agenda even if the wording changed in the time between creating the agenda and the meeting. There was no need to make copies of the information or manually update it in another document.

Agenda document with linked artifacts and embedded artifacts

To make it easy for the project team, I created 2944: $$ Summary – Selected Guidance. The title of this guide begins with dollar signs so that it sorts to the top alphabetically in the Glossary view.  Among other information in that document is a collection of rejected terms (1853: terms – rejected ), which communicates the deprecated terms in a prominent way.  When more terms are added to this collection, they are visible in the summary doc with no extra work.

Portion of the summery doc showing an embedded collection

The first review and approval cycle

To approve a large initial set of terms we used a Rational Requirements Composer informal review artifact. The editor and a senior writer were approvers. The other members of the terminology group were optional reviewers. We used an informal review artifact so that updates that were made to the terms during the review process would be visible as people reviewed the terms. By contrast, formal reviews use specific versions of the artifacts through the whole review process.

When the review was created, everyone in the group received an email that contained a link to the review. A link to the review was also in the Reviews widget on the project dashboard.

the Reviews widget in the dashboard

This is the review artifact itself.

the review artifact

The review artifact provides two perspectives: a participant view and an artifact view. In the review artifact, we each have visibility into the progress of the review.  As the initiator of the review I could easily judge when the group was done by looking at two things:

1. The review status of each artifact

Review progress on a particular artifact

2. Each person’s review activity

Review progress of each participant

After this large, initial review and approval cycle we now work to gain consensus in our regular meetings. In each session, we address a small number of terms.  We aim to finalize terms in the same meeting and move on, rather than asking members to return to a term later and use extra time and effort to remember the term, think about it, and indicate approval.

Example of approval status shown in a column

The benefits of an integrated glossary

To be helpful, definitions must be easy to find. Rational Requirements Composer uses rich hovers for this purpose. When the user hovers the cursor over a link, additional information, which in this case is a term definition, is displayed in a rich hover.

A rich hover showing a definition

If a term has an acronym, synonyms, or alternate spellings, you can enter those in the Alternate Spelling field.

When you view the term artifacts, the Alternate Spelling field is in the sidebar

While you edit, you can search for a term by highlighting a word or phrase in the artifact and clicking the Lookup Term icon in the editor bar.

An author about to create a term link

The RM application searches primary and alternate spellings. After you select a spelling (or create a term), that spelling and a term link are inserted into the artifact.

An author in the process of picking an alternative spelling for this term link

After you save the artifact, the term rich hover is available when you view the artifact.

Readers have direct access to definitions

Summary observations

• If you are innovating, you will be more successful if you create a glossary and an organizational process to evolve concepts and the terms that capture them.
• Start simple in early planning and organization, and then add complexity only when you need it.
• Distributed project teams can be more productive using a team-aware and term-aware tool like Rational Requirements Composer.

---

About the Author

Daniel Moul is a member of the Rational Strategy and Offering Delivery team. His focus is requirements in the development lifecycle.  He has been working on and around enterprise software tools and runtimes for the last 15 years.  Daniel was part of the team that initially brought Rational Requirements Composer to market, and he established the RM terminology working group.