How to write your best documentation in a collaborative world

Working as a team allows us to tap into a pool of diverse experience, skills, and strengths. But how can we align the different perspectives and expectations?

Text by Matt Reiner


Image: © sturti/

We can all relate to the difficulties of writing documentation on our own. Creating something from nothing can be a difficult task. But in the pain of composition, we have the opportunity to turn our own thoughts into a valuable resource for our readers.

While we can create something unique by ourselves, there are different challenges when working as part of a fast-moving team. Not only are we left with the responsibility of documentation, but we may also use tools or processes that actually discourage others on the team from contributing. For this reason, a number of cloud-based collaborative writing tools and processes have grown in popularity. These tools have ushered in a new era of collaborative writing that has improved the way content is created.

  • Teammates can contribute to documentation quickly.
  • Subject matter experts can review content easily.
  • Everyone has access to the content.

While these new capabilities contribute to a more powerful and inclusive workflow, we as writers can't expect everything to remain the same. Collaboration brings new challenges that can help us to be better writers and stronger teams.


As we begin working with a spectrum of personalities, it can become very obvious how differently we all think about certain topics. Rather than seeing our different perspectives as a drawback, we can focus on the benefits of having a diverse set of opinions reflected in our content.

Promotion vs. prevention

The people we collaborate with tend to focus either on the big picture or the small details. Promotion-focused individuals are "big thinkers". They work quickly, take risks, and assume all will go to plan. Taking big risks can often yield impressive results.

In contrast, prevention-focused individuals are "detail thinkers" who work more slowly, focus on the details, and plan for the worst. While their contribution may not seem grand, catching a small mistake can make or break the success of a team.

As we collaborate on documentation with our team members, it's important to include insights from both ends to ensure that our technical content contains all the major themes as well as the crucial details needed to make our users successful.

Introversion vs. extroversion

We're all energized by different things. Some of us are stimulated by the presence of and interactions with other people, while others might just need some silence to focus and re-energize. This behavioral concept is known as extroversion and introversion.

An extroverted individual does their best work in the outer world of people and things. These people are often outgoing, dynamic, and thrive within a group. As team members, they are prone to start writing quickly, sometimes without a proper plan in place.

Those who are more introverted gravitate toward the inner world of ideas and images. Reflective and reserved, these team members are often at their best when working on content alone. They can sometimes get lost in their thoughts, forgetting to check if their ideas and assumptions align with reality.

When collaborating as a team, it's valuable to understand where each team member is on the introversion/extroversion scale to know how they can best contribute to documentation. For some teammates, the best way to write and review might be an in-person session, whereas others might benefit from an asynchronous review where they can think things through and leave comments on the content.

Leading from within

When writing alongside different personality types, we must understand how to lead them. At first, this might seem odd, as we generally view management as the leaders of our teams. Instead, we must be the leaders within the team to help our teammates think outside the box and collaborate well.

To understand how to collaborate with others, we must first be fully aware of our own strengths, temperament, work and communication style. Being self-aware enables us to focus on the strengths of others.

By understanding the team's strengths, we can write from a place of humility and the team can thrive relying on each other's skills. This removes issues of envy or competition and replaces them with a dependence on each other's abilities.

Knowing our teammates’ strengths also enables us to use our own curiosity to draw them into new ways of thinking. Being able to ask questions that spark our colleagues to think from a new angle enables the team to document from a user's perspective.


Figure 1: A modern writing tool enables anyone on the team to quickly collaborate in context.


While working with many different people, the ability to improve each other's writing using feedback becomes essential (see Figure 1).

It's key to understand various types of feedback that can be used, and which types to avoid.

Open dialog

Trust is not something that takes place right away, yet it is essential for effective collaboration. To give and receive feedback, the entire team must feel that they are part of an open dialog where any idea, correction, or improvement can be brought up. This can be particularly hard to achieve if members of the team have been hurt by careless feedback in the past.

To begin a respectful dialog within the team, we must be willing to put ourselves out there. It's not the task of a manager to create healthy feedback but rather ours, as members of the team. To begin the free flow of feedback, we need to share with the team what we need feedback on and how we'd like to receive it. 

Types of feedback

With a trusting dialog in place, we're bound to encounter more feedback while collaborating. This is particularly enhanced by writing tools that streamline the ability to give feedback through commenting and @mentioning. The effectiveness of feedback given relies on the way it's given within the team.

While it can be motivating to get positive feedback like "This sentence is great!", this won't really help anyone improve in the future. The best way to praise great work while encouraging improvements is to use constructive feedback. The value in feedback like "I like the tone of this sentence, but you could consider shortening it" is evident and actionable. The person receiving this feedback can apply it immediately as well as in the future.

Avoid giving negative feedback. Statements like “I can’t understand anything in this sentence" will demotivate the person receiving the feedback and won't show them how to improve. This undermines healthy collaboration.

Modeling feedback

To show our team members how to give healthy feedback, we can model it ourselves. It's best to balance the use of positive and constructive feedback. Also, when negative feedback takes place within our team, we must tell it like it is. It's important to use our healthy feedback skills to show how people can improve their own.


Figure 2: In a modern writing tool, the team can write together to create the best documentation.


With everyone able to share feedback and contribute, it may be obvious who is passionate about documentation and who isn't. While not everyone we write alongside will be as passionate about content as we are, we can all share a common motivation to contribute.


When the entire team works together on content, it can be easy to lose sight of the value we offer as technical communicators. With everyone contributing to content, giving feedback, and making corrections, it can make our role as technical communicators seem easy to replace.

We should keep in mind the unique skills we offer the team and share our individual successes. We can also seek out a mentor to help us focus on personal growth and to identify personal projects to help us work outside of the norm and be creative.

Understanding the abilities we bring to the team is essential as we share our passion for technical communication with others and help form a shared set of values within the team.

Increasing awareness

It's easy for accomplishments to get lost in our day-to-day work. This is especially true given how easy modern writing tools have made it to review content, give feedback, and move on. It's common for collaborators or outsiders to never even see the final version of content. To showcase the great work done through collaboration, we must share the outcomes within and outside the team.

We can share what's gone well, what we've learned, and what we've yet to figure out. This type of valuable information can be shared in team standup meetings, or as internal blog posts, email newsletters, or in whatever format is most suitable. The goal is to have a mechanism for sharing accomplishments and helping everyone collaborate better in the future.


Having the team share their entire writing process is a big challenge. While it's difficult to be open and honest about the content creation process, teams thrive in a transparent and collaborative environment.

The ebbs and flows

There are days when we can write lines and lines of high-quality content, and then there are days when we struggle to deliver even a comprehensible paragraph. This is how writing works, but it's hard to be honest about that with the rest of our team.

All members of the team create in one form or another, and each of us has varying outputs day to day. Just as with writing content, writing code, creating marketing campaigns, or planning new features, it can be a slow process one day and a boom the next. Once we've come to grips with the fact that creation is a series of drafts, revisions, and constant iteration, we can be honest and truly collaborate with our team.

Pair writing

Sometimes it can be beneficial to write in pairs. Pair writing, like pair programming, is the process of two people writing the same piece of content at the same time. This is best done using a tool with a collaborative editor so you can both make changes at the same time. This will seem haphazard at first, like two people trying to drive a car at the same time, but it's a great way to train new writers or to bring a subject matter expert (SME) and a writer together.

Pair writing can be effective when writing about a new subject we don't have much experience with or when revising some old content. Peer writing alongside an SME at the beginning of the writing process can help quickly assemble a first draft of the content, which includes many important details that might otherwise be missed.

Another situation in which pair writing is helpful is as a response to masses of feedback going back and forth regarding the content. This is often a sign that important content is missing or hasn't been explained properly. This is a good time to sit down with an SME and straighten things out in person.

While it may seem as if pair reviewing with an SME will take too much of their time, it typically saves time because many important details are clarified much earlier in the writing process. This makes content review and feedback much faster.

From pain to passion

Collaborative content creation involves working with all sorts of people who have unique opinions and passions, with whom we have to share the writing process. It can be scary and rather painful at times. But challenges notwithstanding, collaboration allows us to embrace the power of diversity and community in an otherwise lonely and one-sided creation process.

So, the next time we're feeling the pain of composition, we should seek out the passion of collaboration.