Additional Blogs by SAP
Showing results for 
Search instead for 
Did you mean: 
Product and Topic Expert
Product and Topic Expert
When using documentation about software products, have you ever come across terms that you have no clue what they mean? As a UX writer, technical writer or information architect, how do you ensure you’re using exactly the same terms that your customers use in the industry? What if you’re documenting a new product in a new area and are just not sure if your research is enough?

Such situations give you enough reasons to do one thing – to conduct customer workshops to validate your findings. In this blog post, we focus on two things:

  • Sharing our experience and insights about running customer workshops for validating documentation terminology definitions, and

  • Why it’s so important to run such a workshop

Source: Adobe Stock

The Review Process

Documentation almost always undergoes a review. One or more people within your company can be involved in the review process, such as subject matter experts, product consultants, other writers, and so on.  Reviews and feedback are an essential part of documentation because you get to know if you’re using the terminology that end-users actually understand!

However, there is usually a little uncertainty whether the terms and definitions that you use in are in fact what your customers use. You do make a few assumptions but also rely on research and information from subject matter experts.

The Situation That Led to a Customer Workshop

One of our products was being developed from scratch in a new product area. Since it was a new area, a lot of extensive research was done by the project management, the User Experience (UX) colleagues, and the User Assistance (UA) colleagues. (To know more about UA in product documentation, see my earlier blog post What’s the Buzz About User Assistance?). The UA colleagues realized that everybody seemed to have a different opinion about the terms that needed to be used!

Wondering what a UA colleague has to do in this case?! Conduct a customer workshop for validating the terminology, of course!

Different Opinions on Terms from Colleagues (Source: Adobe Stock)

Preparing for and Running a Terminology Workshop

For a customer workshop, choose the user personas that you require, and invite the relevant people from your customer organization. Align with your teams about the concepts you’d like to validate, and plan to validate usability, the software or product flow, and terminology.

To validate terminology, you can use a variation of the card sorting technique with your workshop participants. You can place terms and definitions in different cards, randomly place them in a virtual whiteboard tool (for example, at SAP we use MURAL and Figma), and ask your participants to rate or sort the terms accordingly.

(If you’re interested to know more about card sorting, take a look at my earlier blog post Content Harmonization in Product Documentation. For insights about user research and personas, here’s another of my blog posts Best Practices for Defining Your Target Audience Before Writing Documentation.)

Also, a suggestion would be to keep some time for getting feedback from the workshop participants at the end. Check with them about what went well, what they’d like to be done better, or what they feel about the workshop overall. It’s important to incorporate their suggestions in the next round – it would result in a better workshop experience for them.

Preparing and Running a Customer Workshop (Source: Adobe Stock)

Advantages and Importance of a Terminology Workshop

What you gain from such a customer workshop is simplification of terminology. Firstly, you eliminate assumptions and the subjective factor. There might be a situation that you’re creating a new term or definition for an already established industry concept. By validating your terms and definitions, you get to hear from the customers whether you’re using the right terminology or not.

In the customer workshop that was conducted by our UA colleagues, the participants right away pointed out that a particular term was not used in the industry at all and also shared the right term that needed to be used. Another advantage was that a lot of terms finally got ditched because the team was able to simplify their terminology. This surely made a lot of lives easier! What the entire team gained from this terminology workshop with customers impacted a lot of development processes and was a revelation in many ways.

Also, the workshops conducted by the project management were steering the team towards a simplified design. The UA workshops helped achieve more in this direction because the customers paid close attention to a concept-wise breakdown of the product components and decided that some components were simply unnecessary! So you see that you can not only simplify terminology but also product design in such a workshop!


In a gist, terminology workshops with customers is a much-needed information architecture task and must be planned accordingly. Customer workshops are usually conducted before the start of a project or standard development. The user research that you do in this phase of a project is very important. The insights from such research as well as any other research that is conducted by the project management go a long way in establishing concepts and terminology. Interactions with customers teach you never to make assumptions or guesses, and that “universal” or “commonly understood” terms may in fact turn out to be not-so-universal or commonly understood! Last but not the least, such workshops help you in following the “know your audience” guideline that we as technical writers or UA colleagues ought to follow.

Never Assume (Source: Adobe Stock)

Did this blog post help you in understanding the importance of customer workshops in documentation and user assistance? Did it help in showcasing some of the long-term advantages and impact these workshops can have on information architecture and development processes? Do let us know your thoughts in the comments. Feel free to share this blog post with a friend who might benefit from it too.