I just completed a year and a half project at work where we worked on a guide to explain how technical writers can work effectively with UX teams. It was a rewarding project to work on because I was able to engage with UX teams from across the company and learn how they want to engage with technical writing teams.

I can’t share the full guide here, but I will share an adaptation of my contributions to the project to help capture some of what I learned.

What is UX and how does it impact technical writers?

UX stands for user experience and its overall goal is to ensure that customers have positive interactions with a software product because it is easy to use. Technical writers share many of the same goals and there are many ways that these teams can benefit from working more closely together to improve software products.

UX has three main focus areas:

• User research
• User experience design (UX design)
• UX content writing

UX and technical writing teams can benefit from collaborating together at various stages in the software development lifecycle. Both UX and technical writing teams want to improve the customer experience and they both have different perspectives and strengths to offer.

🔍 User research

In this focus area, the UX team’s goals are to:

• Research what customers want or need from a product through a variety of methods including customer interviews, surveys, focus groups, usability tests, and more.
• Use customer research to inform product development priorities and improvements.
• Create user personas, which are fictional characters that represent real segments of users based on their job role and product needs. Personas help product and development teams empathize with their users and better understand their needs.

This focus area has many potential benefits to technical writers:

• Technical writers can benefit from the research gathered by UX to learn more about the audience they are writing for.
• User personas provide more context for the documentation you write, helping writers to empathize with their audiences and understand the tasks they need to accomplish.

Technical writers can provide benefits in return to UX teams in this focus area by:

• Helping to capture notes and observations during user research sessions and share observations.
• Drawing on their own experiences as writers for the technical audiences to provide additional insights about user personas.

✨ UX design

In this focus area, the UX team’s goals are to:

• Collaborate with product managers and developers to understand the requirements for new feature requests and product improvements.
• Create user stories and end-to-end user journeys for new features and product improvements. User journeys are step-by-step paths that a user takes to achieve their goals while using a software product.
• Create user interface mockups of changes to the product and work with developers to get buy-in on final design.

This focus area has many potential benefits to technical writers:

• Writers can get early insights into product changes and begin planning updates to the documentation.
• User interface mockups can help writers gain a more in-depth understanding of the product changes and the customer journey as they update the documentation.
• Writers can produce more effective, task-oriented documentation when they have a better understanding of the context for the product changes from the user’s perspective.

Technical writers can provide benefits in return to UX teams in this focus area, such as:

• If writers are involved in the design phase, they can advocate for the user and ensure the product is as user-friendly and self-documenting as possible.
• As product changes are under development, technical writers can help test the designs early and identify usability issues while they are experimenting and learning about the product changes.
• Writers can help craft effective user stories and offer insights about user personas.

✒️ UX content writing

In this focus area, the UX team’s goals are to:

• Create onscreen text, labels, messages, welcome emails, tooltips, signposts, embedded help, or any customer-facing user interface text.
• Ensure consistency in the word choice and terms used throughout the user interface by creating and maintaining style guides, content pattern libraries, word lists, and databases of common strings.
• Consider accessibility and localization needs when creating UX content.

This focus area has many potential benefits to technical writers:

• Improves the customer experience and their success with the product by providing the information in the user interface (UI) where the user needs it.
• Technical writers and UX share a goal to ensure that the product’s terminology is as intuitive and user-friendly as possible. To reduce confusion, both teams should work together to confirm that these terms are used consistently across the in-product content and the documentation.
• Reduces the burden on the external documentation to explain everything.

Technical writers can provide benefits in return to UX teams in this focus area, such as:

• Writers can draw on their expertise with the product, end-users, and best practices for word choice to provide valuable insights and feedback about UX content.
• Writers can help provide the technical details needed for signpost help and other content that would benefit from technical writing expertise.

Preparing to engage your UX team

If you want to reach out to your UX team for the first time or if you reaching out again after your relationship with UX has lapsed or grown stagnant, these sections can help you think through some important considerations before you begin.

Consult your manager

Ensure that you first have a discussion with your manager about your goals and plans for engaging with UX. Make sure you are prepared for that conversation: think through your goals and how you want to reach out to UX.

In addition to ensuring you have your manager’s support, they can provide helpful advice to:

• Refine your engagement goals and plan.
• Help you determine if you have enough time and capacity to offer support to UX.
• Identify additional stakeholders.

As part of your plan for engagement with UX, you and your manager might consider setting up quarterly meetings with UX and PM (product manager) to discuss features that might need your assistance.

Identify your UX team and stakeholders

Work with your manager and your fellow team members to determine who belongs to your product’s UX team. Additionally, you might need to identify who serves in these roles for your product:

• Product managers
• Front-end developers
• Back-end developers

Even though they are not technically part of the UX team, they are stakeholders who interact regularly with UX. You might need to identify these individuals and get their buy-in for engaging with UX earlier in the development cycle.

Define your UX engagement goals and desired outcomes

You’ll have a more productive and collaborative relationship with your UX team if you determine what goals you hope to accomplish by engaging with your UX team. Ask yourself what outcomes you’d like to see for you and how these outcomes can help you write better documentation and/or improve customers' overall experiences with the product.

Consider what support you can offer to UX in return

You can feel empowered to determine what level of engagement you want to have with UX for yourself. You might get higher quality and more consistent engagement from your UX team if you offer to help them meet their goals because they’ll recognize you as an important team member who adds value throughout the product development lifecycle.

Technical writers can offer many different types of support to UX throughout the development lifecycle, such as:

• Providing advice about product changes during the mockup phase to ensure the product is as user-friendly and self-documenting as possible.
• Reviewing UI strings and ensuring consistent word choice and terminology throughout the project.
• Inviting your UX team to review your documentation, which gives them an additional opportunity to verify that product features and changes remained true to their original design and intent after development.
• Giving advice and feedback to UX designers who might want help refining user personas, user stories, customer journeys, or settling debates about word choice.
• Acting as an early user tester by learning about and experimenting with upcoming changes to the product as as part of their documentation research.
• Taking notes and capturing observations during user research sessions.
• In some cases, UX conducts research on a new product feature and discovers changes that need to be made to the product design because of user friction. (User friction is anything that can prevent a user from completing a desired task with the product.) Often, these research findings come too late in the development cycle to be corrected in the current version of the product. When that happens, the UX team can let the IX writers know about these possible areas of friction and collaborate with them to determine how the documentation can reduce confusion and communicate workarounds.

However, you don’t need to feel obligated to offer this support if you don’t have the time or workload capacity to offer this level of support to your UX team. At a minimum, technical writers can benefit from at least reaching out to UX and:

• Getting agreement to be included in meetings or communications about upcoming product changes.
• Having early access to UX product design documents, such as user stories, user journeys, and more.

Decide which stage of the product lifecycle you want to engage UX

In general, UX designers tend to be more heavily engaged during the beginning phases of the product development lifecycle, and stay actively involved only through the end of the development phase.

Sometimes technical writers are only brought into the product lifecycle as late as the testing or release phase. While involving writers at the testing phase is common in waterfall software development practices, technical writers working in an Agile software development cycle should try to be involved earlier in the cycle.

As the authors of the book The Product is Docs state:

If you write your first words about a feature after the development is finished, you aren’t Agile. … In an Agile environment, you need to be an adaptable, proactive self-starter. Most of the other scrum team members won’t habitually think of reaching out to the documentation team to notify you that a feature or enhancement has a documentation impact. You need to watch for and track down the information (p. 8, 12).

One of the best ways to ensure that you are involved earlier in the product lifecycle is by engaging with your UX team to ensure they remember to invite you to relevant meetings and add you to important communication channels.

If you try to be involved in the planning stage, you might find that it is too early to make a meaningful contribution and it might overlap with the documentation work you’re doing in preparation for a release. But if you don’t get involved until after development, you will lose an opportunity to gain a deeper understanding of the intent and motivation behind the product changes from UX.

Consider discussing when you should get involved in the product lifecycle with your manager and your UX team to determine what is best for your team’s workflow. You might also consider negotiating the conditions under which you should be involved since not all feature work might benefit from your direct involvement.

Reaching out to UX for the first time or after a long gap

After you’ve determined your goals for working with your UX team and discussed your plan with your manager, it’s time to reach out to your UX team. One of the best ways to establish a healthy collaborative relationship (or to re-engage with your team after the relationship has lapsed) is to hold an initial discovery meeting with your UX team.

The goals of these discovery meetings are to:

• Persuade or remind the UX team about the value technical writers can add to the UX workflow and how their business goals are aligned.
• Establish a human connection and create a mutually beneficial working relationship between UX and technical writing teams.
• Learn more about your UX team’s current processes or workflows for working on product changes or initiatives.
• Brainstorm ways in which technical writers could best fit into the existing UX workflow without too much additional logistical work or overhead.

Ultimately, you want to ensure that you and your UX team are aligned and that you agree about the path forward.

Request a discovery meeting with your UX team

You can send an email or Slack message to your UX team to gauge their interest in holding a discovery meeting and to inquire about schedule availability. For example:

Hi {their name},

I’m {your name} and I’m a {your role} on the {product name} team.

If possible, I’d like to meet with you for about 45 minutes to learn more about your general process for researching, designing, and working with developers on product changes. My goal is to explore whether there are any points in your workflow where you feel it would be valuable to include me in the process.

One reason I’d like to meet is because I feel I can create more useful, higher-quality documentation if I can get a deeper understanding of product changes earlier in the development cycle. I also think I might possibly be able to offer helpful support by collaborating or giving feedback on user-interface text in product mockups to ensure usability and consistency in the product.

Would you be available some time this week or next to discuss your workflow and share your perspectives with me? If so, let me know what times would work best for you.

Thanks,

{Your name}

Run an effective discovery meeting

As a general best practice, try to make this meeting a semi-formal discussion. Think of it as an opportunity to listen, learn, and discover more about your UX team and a chance to explore how you could collaborate more effectively with them to meet both your business goals and theirs. It’s possible you might not get exactly what you hoped for, but it’s a good opportunity to negotiate and find a mutually workable solution.

Here’s an example of a possible agenda:

1. Icebreakers and introductions - If this is your first time meeting the team, you can take a few minutes to introduce each other and learn a little bit more about each other. If you already know each other, this is a good chance to catch up with them on a more social level.

2. Purpose of the meeting - To transition to the next part of the meeting, restate your purpose for calling this meeting, which is to learn more about your UX team’s current process and explore areas where you could collaborate with them. In this part of the meeting, you could possibly talk about the goals that technical writers and UX designers share in common and how improved collaboration helps to make the product better for customers.

3. UX team processes - In this segment of the meeting, your goal is to learn more about how your UX team’s workflow. You want to learn how they take a new product initiative from an initial idea to a fully formed product feature or change. Some questions you could possibly ask:

   • Tell me about your process or workflow for working on a new product change or feature. How do you work with product managers and developers at various stages of the product development process?
   • Which meetings or communication methods do you use to collaborate with product managers and developers about product changes?
   • What is your current process for developing UX content, such as on-screen text, signposts, and tooltips?
   • Are there any things about your current workflow or processes that you wish were better or where you would prefer to have additional support from the rest of the team?

4. How technical writers can fit into the UX workflow - After you have a good understanding of what the current UX process is, you can then begin to brainstorm ideas and negotiate how you can fit into their process. Be clear that you don’t want to make any extra work for anyone and that you’re looking for solutions that will be mutually beneficial for everyone. One way to ensure this portion of the meeting is effective is to possibly mention your goal or desired outcome.

   • If your goal is to get early access to mockups, ask where they think would be best to involve you. For example, if they already share the mockups with the product managers or hold initial meetings with the developers, ask if you can be included on those communications or invited to those meetings.
   • If your goal is to attend UX demos of upcoming product changes, ask if they currently have such demos and if they would be willing to invite you in.
   • If your goal is to ensure that UX content (such as user-interface text) is user-friendly and is consistent with the product documentation, ask if they would like you to review UI strings and other UX content. NOTE: You might need to educate yourself about UX content best practices before offering this kind of assistance.

5. Summary and follow-up with additional stakeholders - At the end of the meeting, summarize any decisions or action items that have been agreed on. Try to keep these action items specific, simple, and actionable, such as “The lead UX designer will add the technical writer to the weekly product and development sync meetings” or “The technical writer will schedule a follow-up meeting with the UX designer to create a decision tree that explains what kinds of product initiatives should include a technical writing review.” Also, take a moment to ask if there are any additional stakeholders that need to be informed of these decisions. You might possibly need to inform or get buy-in from product managers and developers, for example.

Document what was agreed on and follow up after the discovery meeting

After a successful discovery meeting, one best practice is to send a follow-up email documenting any decisions or action items that were made in the meeting. This meeting documentation will help you in a few ways:

• Meeting attendees can later refer to this record to refresh their memory on what was discussed and remind themselves about any short-term action items they agreed to take.
• Sometimes people don’t always keep their agreements or follow the processes that they mutually agreed to. Usually, people don’t do this maliciously, but simply because other priorities came up or they forgot about the agreement because they were distracted by something else. Having a meeting record gives you a paper trail that you can refer to if you need to gently remind people about a promise they made to you and ask for future action.

Troubleshooting strategies

Even if you’ve done everything you can to have a productive relationship with your UX team, you might still experience some challenges or obstacles. These strategies can provide you with ideas for resolving common challenges that could arise when working with your UX team.

What if my UX team agrees to collaborate with me, but then doesn’t follow through?

It’s possible to be in a situation where you had an effective meeting with your UX team and reached a mutual agreement, but then you don’t see any of the requested process changes or action items. When that happens, usually the UX team might possibly need a reminder of what was agreed upon and what action items they agreed to take. Usually, an email or Slack message reminder is enough.

For example, you could write:

Hi {their name},

It was great to meet with you last week to talk about how I can better collaborate with your team.

I wanted to touch base about {action item}. Did you have a chance to work on that yet? If not, is there anything I can do to possibly help?

Thanks,

{Your name}

If you begin to notice that it is taking a long time for the UX team to follow up on their action items, it’s possible that there was a misunderstanding about the agreement.

It’s also possible that they are feeling some hesitation about what was originally agreed upon in the meeting. Sometimes people agree to take an action or make a particular process change, but later begin to second-guess the decision.

If this is the case, the best solution is to have another conversation to establish trust, reduce confusion, and ensure that you still have their buy-in and alignment. Make sure that you listen to any concerns that they might have and work collaboratively to resolve those issues.

What if my UX team doesn’t take my suggestions?

As you most likely know from your own experience asking for feedback on your documentation drafts, sometimes people feel nervous or insecure asking for feedback on their work, especially when working with a new reviewer. To help establish trust with your UX team while also providing a high quality review, consider these strategies:

• Begin by first asking the UX designer what kind of feedback they are looking for and if there are any specific areas of concern where they’d like your specific insights.
• Don’t just focus on the negative. Make an effort to make at least one genuinely positive comment and/or mention that you like the overall design (and explain why).
• Clearly explain your reasons for making a specific suggestion. For example, if you are basing your suggestion on a style guide, you could reference that section of the guide.
• If possible, try to offer more than one way to change a word or phrase so that the UX designer has a few choices to consider.
• If you’re communicating with the UX designer mostly in Figma, consider setting up a meeting with them to discuss your suggestions in real time.
• Indicate if your suggestion is open for discussion or if you feel very strongly about the change. In most cases, you should treat your suggestions as open for discussion and only reserve your strong suggestions for truly important issues, such as potentially blocking issues.
  • If you don’t feel strongly about your suggestion, consider using some phrases to soften your suggestion and signal that your feedback is open to discussion. For example: “Have you considered…” or “I’m open to discussing it. What do you think?”.
  • If you do feel strongly about your suggestion, make sure that you explain why it’s your preferred solution and indicate that it’s important when leaving a comment. For example, you can label the comment as important or a blocker. Depending on your situation, an effective approach might be to advocate for consistency across the UI and the documentation. Use your best judgement.

Remember that this is a collaboration and that the UX designer ultimately gets the final call on whether to adopt a suggestion or not. Even if they don’t adopt your suggestions, they will still likely appreciate that you gave them a new approach to think about and consider.

You’ll also likely get better at providing high-quality feedback with more practice over time and it’s okay to ask your UX team to have patience with you while you are learning. If you find that the UX designers are not implementing your feedback more often than not, consider having a discussion with them about how you can provide better, more actionable feedback. Use this as an opportunity to learn.

What if my UX team is resistant to working with me?

Even if you suspect that your UX team is resistant to working with you, you should always begin by assuming good intent from your UX team. Most UX teams want to work with technical writers.

However, sometimes the relationship begins to lapse. When that happens, it is often for reasons that have a simple explanation, such as:

• UX teams get busy and are distracted by other work priorities.
• There might be an extended period of time where collaboration isn’t as necessary and the teams fall out of the habit of communicating with each other.
• Processes and workflows aren’t working and simply need to be re-examined and adjusted.

The best approach is usually to have an open and honest conversation with your UX team about your concerns. Often you’ll find that there was a genuine misunderstanding or a simple oversight that caused the relationship to lapse.

If you find that your UX team doesn’t respond to requests for a conversation of if there are other unexpected behaviors, it might be best to discuss it with your manager. Your manager can provide a second opinion about whether your UX team seems to be genuinely resistant or not.

Your manager might also have additional information about the situation that you are unaware of and can work with you to brainstorm ways to work through the challenge. If your UX team’s behavior is persistent and doesn’t get better over time, your manager can also help to escalate the matter if truly necessary.

What if my UX team requests my assistance, but I don’t have the bandwidth to help?

Sometimes UX might reach out to you with a request that you might not be able to take on. Perhaps you’re busy working on documentation for a fast-approaching release and it’s difficult to find time for additional tasks. Perhaps you are already juggling extra projects on top of your doc deliverables. Or perhaps you feel like you don’t yet have the necessary skills to provide useful input. Whatever your reason might be, it’s okay to say no. Remember that working on in-product UI content is not strictly a technical writing task.

If you decide to decline the UX request, make sure you do so politely and respectfully. Explain why you are not able to assist. If you are generally open to assisting UX with UI content, but you can’t at that particular time, let them know that the timing is bad right now but leave the communication channels open. This way, UX won’t be discouraged to reach out to you again in the future.

If you’re unsure what to do, talk to your manager. They can help you find a solution. For example, someone else on your team might have the bandwidth and be willing to step in.

Conclusion

I wish you success in your journey toward a healthy collaboration with your UX team. Any relationship that is worth cultivating requires some hard work to establish, nurture, and maintain over time. Hopefully, you will have a rich and mutually rewarding collaboration with your UX team that will help you grow professionally and that will improve the user experience for your customers.