Working effectively with other teams as a technical writer

Alyssa Rock — Tech writer. OSS community manager. DocOps enthusiast.
Dec 15, 2022, updated Apr 22, 2024 18 min read

Much of your success as a technical writer depends on the quality of your relationships with co-workers on other cross-functional teams. As the writers of The Product is Docs state: “Technical writing is a relationship business” (215), meaning your success as a writer depends in large part on your ability to collaborate effectively with co-workers in key roles for your software project.

In this guide, I hope to inspire you by showing you how these relationships can enrich your documentation work. Keep in mind that building strong relationships with your co-workers could be deeply rewarding for you. Many studies show that co-worker relationships have a direct impact on most people’s overall workplace satisfaction. But you don’t have to befriend everyone immediately at work. Consider which relationships are the most important to focus on strategically and begin building first.

The following are some of the common teams you could engage with in order to improve and enhance the end-user documentation:

Team member Role
Product Researches the new features or improvements that customers need from the product and creates the product roadmap.
UX Works with product managers to define the requirements for new product features or improvements. They create user stories and UI product mockups for product changes. Their goal is to ensure the product is easy to use and meets customer needs.
Engineering Uses their programming skills to turn requested product changes into reality. They ensure all product requirements for new features are met and they resolve any product bugs or issues as they are reported by customers or stakeholders.
Customer support Works to resolve any technical issues or difficulties that customers experience while using the product. They report bugs, errors, or usability problems to the engineering teams.
Marketing Helps potential customers get interested in the product. They create content that demonstrates how the product solves common problems or important customer problems.
Field engineers Works directly with customers to help them deploy, use, and adopt products. Typically, these individuals have expertise in the product and advanced knowledge of the product's domain area.

All of these teams are stakeholders for the documentation. Each team cares about the success of the documentation and they play a key role in creating and improving the documentation. In this guide, you’ll learn some strategies and best practices for working effectively with these teams.

Product management Product management

Product managers are a key role for all software teams. The overall goal of product management is to ensure that software products deliver value to customers and that your products are competitive in the marketplace. They want your products to be easy to use, easy to understand, and for your products to solve the problems that matter most to customers.

Product managers:

  • Define the overall vision for the software product.
  • Meet with customers and stakeholders to ensure they fully understand what customers need from the product.
  • Analyze user and market research to determine how to stay competitive with similar software products.
  • Create a product roadmap and align all stakeholders around the roadmap.
  • Set priorities and timelines for developing the feature requests and enhancements for the product.

How to work with your product manager

Because product managers want your products to succeed and be easy to use, that means that product managers care about the success of the end-user and in-product documentation as well. After all, the documentation is part of the overall customer experience for the software product too.

For that reason, fostering a productive and collaborative relationship with your product manager is crucial to your success. Your product manager can help you understand how the documentation can better meet customer needs and they can collaborate with you to ensure the documentation aligns with the product roadmap and vision.

For me, I’ve found success in setting up a standing weekly or bi-weekly meeting with the product manager(s) and technical writing team to review key product priorities and exchange ideas about how I can best support those priorities.

UX User experience (UX)

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.

UX teams:

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

How to work with your UX team

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.

I wrote an entire blog post on this topic, so feel free to check it out: UX and technical writers: a powerful partnership.

Engineer Engineering

Also sometimes called developers, engineers build and develop software programs. Their goal is to create functional software that works as it is intended.

Back-end engineers write code for the software’s underlying structure and logic. Front-end engineers work on the visual elements of the user interface. Full-stack engineers are capable taking on both back-end and front-end development tasks.

Engineering teams:

  • Receive development requests from the product management and UX teams and create software that meets the software requirements.
  • Work to resolve any software bugs, errors, or performance issues that are found in the software.

How to work with your engineering team

An effective relationship with your engineering team is critical to writing effective documentation. Members of the engineering team can act as subject matter experts (SMEs) for your documentation, which means they often provide you with the source material for your documentation.

When a new software feature or improvement is nearing completion, you might meet with members of your engineering team to learn how the new feature works and what needs to be communicated to end users. The engineering team might also need to review the documentation you write to ensure it is technically accurate.

To work effectively with your engineering team:

  • Improve your interviewing skills. When you meet with members of your engineering team to get information about a new feature or product change, you want those meetings to be a valuable use of their time. To make the most of your time, prepare high quality SME interview questions ahead of time to make sure you can get the information you need to write high quality documentation. Talk to your manager or members of your documentation team for advice on crafting effective SME interview questions.
  • Build your credibility by developing your technical expertise. Set aside a few hours of your work week to learn more about your software product, its underlying technology, and the deeper use cases or domain area for your product. To provide you with additional motivation, talk with your manager about setting up a learning goal to create an effective learning plan for your product.
  • Set up a working demo environment of your software product on your computer. A working environment can give you a chance to test and experiment with new features or product changes first-hand. Talk to your manager, an engineering team member, or a senior member of your documentation team to learn what options are available to you for setting up a working demo of the software.
  • Establish an open line of communication with the engineering manager. Each engineering team usually has a manager who is responsible for ensuring the engineering team is operating effectively and working on the most important tasks. When you first join a product team, consider setting up a meeting with the engineering manager to set expectations and get alignment for how you plan to participate on, communicate with, and receive or make requests from the engineering team. You could also invite your manager to participate in or lead this meeting.
  • Embed yourself on your engineering team by attending regular engineering meetings. Meetings such as daily stand-ups or sprint planning sessions can give you a deeper sense of what the engineers are working on and demonstrate to them that you are a member of their team. Try to get to the point where you can mostly follow the technical conversations in these meetings by developing your understanding of the product and the team’s key initiatives.
  • Participate in sprint demos, if possible. If your engineering team holds regular sprint demos, try to attend those demos and see the software changes in action. Also try to participate in these demos by asking if you can showcase the documentation work you are doing.

Customer support Customer support

The goal of customer support engineers is to help customers solve their technical issues while using the software product and, hopefully, ensure the customer is satisfied with the product. Because customer issues are often highly technical in nature, customer support engineers need to have in-depth knowledge of the software product and understand how to diagnose and troubleshoot common problems.

Customer support engineers:

  • Triage and resolve customer support issues that are initiated through a phone call, email, a web request, etc.
  • Ensure issues are successfully resolved within the time frame specified in the customer’s service level agreement (SLA).
  • Escalate support issues to the product engineering teams as needed, such as bug reports or performance issues.
  • Report documentation errors or suggested improvements to the documentation team.
  • Write and maintain knowledge base articles so that customers can self-serve, which means solving technical issues on their own before they contact customer support, if possible.

How to work with customer support

Customer support engineers and technical writers share many similar goals: reduce the volume of support calls by helping customers to solve technical issues with the product on their own. Both teams want to make the software product easier to use, learn, and adopt. For that reason, customer support engineers and technical writers are natural allies.

Even though they are natural allies, technical writers don’t always have direct interaction with the customer support engineers that specialize in their product. If you feel that it would benefit your documentation to have more direct interactions, you might need to pro-actively seek out and nurture a relationship with the customer support engineers that specialize in your software product.

Be aware that support engineers frequently work with frustrated customers and are under significant time pressures to resolve support requests quickly. For that reason, you might experience difficulties finding good opportunities or enough time to collaborate with support. However, as one of my support engineers once said about the value of working with technical writers: “We shouldn’t be so busy fighting fires that we neglect to focus on fire prevention. We should make time to improve the documentation so that customers can self-serve and solve more of their problems on their own. That will help us prevent more fires before they start.”

To work effectively with your customer support team:

  • Find out who the customer support engineers are for your project and introduce yourself. That will help to establish an open line of communication if they ever need to reach out to you for documentation requests.
  • Let the support engineers know how to open documentation requests. Not all customer support engineers know the best way to open documentation requests for your team. If you tell them how you prefer to receive documentation requests, you’ll increase the chances that the support engineers can let you know about documentation errors or other requests.
  • Try to resolve any documentation errors that are reported by customer support in a timely manner. If you don’t have enough information to resolve a documentation request from customer support, you can always contact the support engineer for clarification.
  • Make sure that all your documentation is technically accurate and up to date before it is published. Customer support is expected to provide support for any tasks, use cases, best practices, or recommendations that are made in the documentation. For that reason, it’s important that the documentation is technically accurate and represents the best workflow for customers. For more complex technical documentation such as high availability or disaster recovery recommendations, you might want to seek out additional validation from the support team before this content is published to ensure they can support those recommendations.
  • Take some time to familiarize yourself with the knowledge base articles about your product. Ask the support engineers which articles are the most popular or helpful and if there are some articles that could either be incorporated into the end-user documentation or that could be linked to from the documentation. You might also want to ask the support engineers about the current process for requesting a knowledge base article.
  • Consider collaborating with customer support to identify trends in support requests about your product. These trends could possibly teach your team more about the pain points that customers frequently experience. Your product manager and UX team might also want access to this data. Some of the pain points might be best addressed through product improvements while some pain points can instead be resolved through the documentation, at least as a temporary stop-gap.

Marketing Marketing

The marketing department is responsible for communicating the value of your company’s software products to external and internal audiences.

The marketing department includes many different people working in a variety of roles, but the roles that you might interact with on a regular basis include the product marketing managers and technical marketing managers for your software product.

Product marketing managers and technical marketing managers:

  • Collaborate with stakeholders to develop the marketing strategy and overall vision for the software product.
  • Write technical marketing content about the software products, including blog posts, tech briefs, and white papers.
  • Manage the content and write the copy about your software products on the products website.
  • Create multimedia content about your software products, including video overviews.
  • Create social media marketing content, such as tweets, LinkedIn posts, Facebook posts, Instagram, etc.
  • Participate in software demos to help market recent or upcoming releases.
  • Manage the product’s presence at industry events and conferences.

How to work with marketing

Technical writers can benefit from a closer relationship with their peers in marketing because both groups care about creating high quality content for customers. In fact, documentation itself plays an important role in the sales funnel. Various market studies show that customers increasingly review the product documentation and that it factors into many customer’s decision about whether to buy a product or not. The documentation gives customers a more in-depth understanding of the software product’s features and helps them assess how easy or difficult the product will be to onboard and use.

As the writers of The Products is Docs state:

You have more in common with marketing than you might think. … By working with the marketing team, a documentation team or writer can gain a better understanding of the target customer, prepare for future changes to the product or target market, and align the customer experience between the marketing content and the product documentation.

To work effectively with your peers in marketing:

  • Collaborate with your product marketing manager to understand the marketing strategy for your product. Once you understand the marketing strategy, you can ensure that the end user documentation aligns with and reinforces this strategy. For example, if the marketing team is putting a strong focus on a particular feature or use case, you’ll want to make sure that any relevant documentation content for that feature or use case is in good condition. That content will likely get the most attention from users after a product release or marketing campaign.
  • Establish an open communication line with the marketing managers so that they can share customer perspectives and feedback with you. Because marketers sometimes interact directly with customers, they might be aware of customer usability issues or pain points where the documentation can help reduce confusion.
  • Identify areas where the documentation content and marketing content overlaps. Sometimes the marketing managers for your product creates useful content that could be consumed by the docs for long-term access. The reverse is also true: sometimes the documentation content you produce could be useful source material for marketing managers as they work to create content for customers, especially for an upcoming release.
  • Set up a regular cadence to keep in touch with the marketing managers. If it’s appropriate for your team, consider setting up a rotating meeting where you check in with your marketing team at least 2-3 weeks before a release. You can use these meetings to ensure there is alignment about the marketing strategy for the upcoming features and to compare content goals to identify any potential collaboration points or areas of overlap.

Field engineers Field engineers

Field engineers often have a variety of titles, including sales engineers, professional services, solutions architects, consultants, etc.

Although their titles may vary, a field engineer is anyone at the company whose primary goal is to work directly with customers to help them deploy, use, and adopt software products. Their primary responsibility is to help customers successfully deploy and use the product so that they’ll continue to use it and renew their subscriptions or contracts in the future.

Field engineers:

  • Empower customers to use the software independently, which increases customer success and adoption.
  • Create proof-of-concept demonstrations to show how the product can help solve the problems customers care about.
  • Create innovative technical solutions to help customers set up their environments quickly and adapt the software to meet the customer’s specific needs.
  • Work alongside customers to drive deployments and resolve complex technical issues that arise while deploying and using the software in their environment.
  • Create a variety of content that is valuable to customers, including white papers, architectural diagrams, or internal documentation that explain how to help customers deploy the product effectively.

How to work with field engineers

People working in the field have more direct customer contact than nearly any other role in the company. For that reason, field engineers can help you better understand the immediate goals and challenges that customers have with the product. These insights will broaden your understanding of the target audience for the documentation, which will ultimately improve your ability to write better documentation.

Field engineers are also strategic, resourceful problem-solvers who have in-depth technical knowledge about the software and the customer’s domain area. As such, field engineers can act as subject matter experts (SMEs) for your documentation in addition to the engineering team. Field engineers have the added benefit of knowing how the product works in practical, real-world contexts since they work closely with customers. Customers find creative and unexpected ways to use the product to meet their practical needs and field engineers see these workflows first-hand. They can therefore provide additional insights that the engineering team alone might not have or they can help fill in knowledge gaps.

Because field engineers want customers to succeed with your software products, that means they also want the end-user documentation to be both useful and technically accurate. At a minimum, they can provide valuable insights if they are included as reviewers for new documentation. Ideally, they can collaborate directly with technical writers to produce high-quality, practical content for customers that can also be included in the product documentation.

To work with field engineers:

  • Ask your product manager to introduce you to the field engineers. Your product manager is the team member who is most likely to have a good collaborative relationship with the field engineers because the field engineers are likely to pass along product feedback and customer feature requests directly to the product manager. If product managers have a regular meeting to talk with the field engineers, ask if you can attend and participate in those meetings so that you can interact with field engineers more regularly.
  • Encourage the field engineers to help make the documentation the single source of truth. Field engineers frequently create and maintain content that is valuable to customers. Some of that content is created for a specific customer. Some content is for the field’s own internal uses that help them do their work. However, some of the content they create can help a broad range of the users for that software product. Field engineers often create this type of content because there was a gap in the existing documentation and they needed a reliable resource. Encourage field engineers to share this content with you so that you can incorporate it into the product documentation, which makes it easier for all customers to find and use the content.
  • Ask field engineers to both test and review the documentation. Field engineers are often eager to get information about features or improvements that are in an upcoming product release. If they are given advance notice, they are also interested in testing beta version releases of the software to ensure it will meet customer needs or that it will be easy to deploy at the time the software is released. If you are preparing new documentation for an upcoming release, consider asking field engineers to review the documentation and possibly test the technical accuracy of the documentation by trying to use the documentation in a beta release of the product. They may welcome the chance to get early insights into upcoming product changes and documentation reviews can provide those opportunities.
  • Keep your processes for interacting with the field engineers as lightweight and flexible as possible. Field engineers have different goals and deadlines than software teams and they might not always be able to help you when you need them to. Be careful not to require field input as a blocker for creating or publishing documentation except when it’s truly necessary. When deliverables require input or assistance from field engineers, try to give advance notice and flexible windows of time for these deliverables. Clearly communicate expectations and deadlines.
  • Express appreciation when field engineers complete a review, provide source materials for the documentation, or pass along customer feedback. Treat their collaboration and involvement as a gift, not as an imposition on your time or as an obligation that you are owed. Let them know that their collaboration will provide value to customers to ensure they will be equally willing to collaborate with you in the future.