Join the 85,000 open source advocates who receive our giveaway alerts and article roundups.
How a Microsoft docs team increased openness and improved collaboration
How a Microsoft docs team increased openness and improved collaboration
My technical content team at Microsoft needed to change the way it operated. Switching tools was easy. Changing our team culture was much more difficult.
Get the newsletter
I manage a technical content team as a part of the Cloud and Enterprise group at Microsoft. And about fourteen months ago, the team was experiencing some serious communication and collaboration issues.
A lack of openness was at the root of them.
This is the story of how my team rediscovered its purpose, found new success through collaboration, and engaged with external contributors and customers in new and productive ways—all thanks to an open approach.
At Microsoft, technical content teams work as part of a larger engineering team to document products available for download. Like other software companies and organizations, we market products aimed at delivering certain business value. Technical content teams, then, must clearly explain how to use software to efficiently do what we've told a customer is possible.
We do this primarily through written documentation. Over time, minor updates to that technical content are insufficient. So we, as technical communicators, must continually evaluate what customers need to do, compare that information against what we know the product can do, and explain how to use the product so customers will be successful and will want to return to the product going forward. This kind of work can require major documentation overhauls frequently.
My team knew this. But too often I observed some team members merely tinkering with very minor updates—changing one or two words, and simply copying and pasting updates from technical experts. The work reflected a lack of willingness to frame a point of view regarding what customers should do with the products we're documenting.
On top of that, everyone was operating as an independent contractor inside a silo of work that they were pretty conscious of protecting. The team had recently moved content from a closed system to GitHub—but was still only paying lip service to the idea that writers would accept contributions from anyone, anywhere. In practice, the team members took great ownership of the content that they'd "authored."
I knew our team culture and behavior had to change. We needed to accept contributions from anyone willing to take the time contribute. We needed to consider a workflow for evaluating contributions and create a community that encouraged contributions. We also had to start working more collaboratively internally.
To do any of this effectively, I knew I needed to help the team rediscover its purpose.
Finding purpose in openness
Our shared purpose became demonstrating a commitment to openness. In our case, "openness" meant that we accepted contributions through an easy-to-learn markdown file format, evangelized for contributions from internal and external contributors, and allowed our internal comments to be visible to an external audience. It also meant that people had to be open to feedback from others.
Transitioning from XML to markdown meant that the workflow changed for everyone on the team. We replaced our proprietary file management system with GitHub, so checking for internal and external pull requests became a new task everyone now undertook. Becoming more expert with git took time; the team was straining to adjust when everything felt so new.
As people were stressed by the content publishing workflow changes, collaborating with stakeholders was also strained. Because people now had less time to do their work, they didn't invest as much in content quality. "Isn't the community available to help with contributions?" a few people asked when they spoke up about quality issues. But management changes and other factors caused these voices to get muffled and silenced.
But the the workflow changes required when moving from XML to markdown, and from proprietary file management system to GitHub, were much easier to manage than the cultural changes required to make the team more open to feedback about the content that we were publishing.
Taking an honest look
For too long, the technical content team hadn't taken an honest look at what was working well and what needed improvement. The pervasive belief was that being critical meant being unkind. But a few long-time team members managed to provide constructive feedback in a way that cracked open the door to a more open team culture.
Seeing the opportunity, I began providing more feedback too: I started to use different words to describe our work. Content developers were no longer authors; they were maintainers. Responsibilities expanded to include reviewing contributions, and contributions came via GitHub. Experience with git was expected to grow over time. We all laughed about our experiences in git hell.
As a manager, I didn't send email with requested changes. I posted comments and pushed commits. I tagged others to take a look at contributions. I shared positive feedback with people who took risks, regardless of the outcome. I changed teammates' assignments until I saw that the person's work aligned with their potential for growth. I worked in the community as much as possible to encourage contributions.
What happened led to an organizational change that continues to surprise and instruct.
A new approach to refactoring
In a period of only ten months, five people left a team that originally consisted of 10. Employee turnover at a tech company based in Seattle is not unusual. That said, when half the team departs, you, as a manager and leader, have an opportunity to reshape the organization in a way that is impactful for customers and the employees who remain with the team. You also think about who stays with the team and how to retain the talent you want to keep. I knew we could do this by doubling down on our commitment to openness.
Finding employees to join a team takes time. The smaller team that remained after each departure banded together to do what we needed to do for our customers. Yes, we made mistakes as we worked to bridge any gaps while also learning how to demonstrate an external commitment to openness. But to make contribution and collaboration easier, we changed the structure of the documentation set stored in GitHub. These changes took months to implement, as we made the changes alongside ongoing updates and the refactoring of content.
When a team decides to refactor content—that is, revise and rewrite it to improve clarity without negatively impacting technical accuracy—it has no guarantee that the refactoring is going to be as successful the team predicts. For example, years ago I worked on a team that spent 18 months refactoring content based on significant customer research. When the changes went live, despite the careful research and planning, customers were unhappy and my team had to undo changes based on clear indications that the changes were leading to large, sustained dissatisfaction with the product.
So as my current team refactored content, instead of making big, bold changes behind the scenes, we pushed smaller, iterative changes when we had smaller batches of new content ready to deliver. If you were to look at the daily updates we made, you'd see only changes that seem minor and small. But over a six-month period, the sum of those "small" changes added up to a substantial amount of quality improvement. One potential downside of taking this kind of iterative, daily approach is the possibility that you'll learn something later on in the process that forces you to rethink an earlier change. Yet this type of "why didn't we wait?" moment did not occur. By making updates in bite-sized chunks, we found it easier to recover when things did not go as planned.
For instance, in our first update, when we pushed the changes live, all of our content went offline. Our service level agreement (SLA) says we'll be online 100% of the time unless we pre-announce a maintenance window. Going offline is a big deal. We quickly realized a configuration setting was the root cause of the outage. Forty-five minutes later, we were back online. That said, for 45 minutes our content was offline—and customers noticed. Instead of posting an excuse, my team owned up to the fact that, in the process of making an improvement, we had encountered an unforeseen problem and worked to fix it as soon as possible. The team survived.
About a month later, when a long-time, trusted contributor recommended a change, I merged the commit without completing due diligence regarding verification. Within a day I realized the usually trustworthy contributor submitted bad information, and I pushed a correction. The readers noticed the changes and felt we had not done an adequate job of explaining the changes. A Reddit thread about the issue soon appeared, and there was a lot of interesting internal and external discussion for about 48 hours. I was OK.
These types of situations continue to teach us things about making updates to the technical content.
Staying the (open) course
However, one of the more interesting discussions that occurred wasn't related to content at all, but rather to the updates customers could read on GitHub. Specifically, commit messages from internal contributors started to display in Bing search results. The team felt like their private messages were becoming public. We talked about whether we should find a way to suppress certain information from being shared externally.
At the end of the discussion, we opted to remain open.
These now-public snippets illustrate things we experienced as a team. As I managed the team, I made more mistakes. But through it all, I learned the following lessons:
- I remained committed to providing constructive feedback to people unaccustomed to anything that might be perceived as negative. Some people responded positively and appreciated my input. Others felt like I was off-base. Some people were quiet, but I could see a change in their actions that led me to understand they had heard me.
- I asked for feedback—and listened when I received it. Someone told that care too much about people and that keeping a little distance might help me have more regular work hours. During the day I tend to spend most of the time talking with people. I find that in email and online chats, people can miscommunicate. Talking to people, in person or using audio- or video-conference, reduces miscommunications and leads to an increase in productivity and employee engagement. People on my team had relied on email for so long that the idea that I would spend time talking with people regularly was unexpected. I worried that I was taking too much time away from "productive work," so I initially hesitated to talk with people in person. But I then remembered that the best teams I have worked with spent more time communicating verbally and in person—not just online.
- In terms of management style and approach, I learned to be a partner and facilitator. When teams are under a lot of pressure, there is a tendency (as a manager) to micro-manage. I do not like to be micromanaged, so I resist the urge to employ that management style. The team members who stayed with me—and those team members who joined as others departed—started to become a team that trusted each other.
The commitment to open meant that we (internally and externally) listened to others, but it was not our responsibility for everyone to be happy with the final outcome. I remembered that an open organization is not an organization that relies too heavily on consensus. The emphasis in an open organization is on collaboration.
After more than 14 months, the team is changing. Yes, half of the original team has departed. But the new team members are not the only change. Original members who remain with the team are now more likely to express themselves freely and laugh at mistakes. I can ask questions that at the beginning of this experience would have resulted in silence. Today those questions more often lead to vibrant discussions. People are willing to take risks because they trust that we learn when we make mistakes. We work through problems in small groups and share what we believe our customers need. There are fewer silos as people are leaning into the notion of sharing their work and not being afraid of being torn apart. We build each other up and open ourselves to a community of contributors, who care about the content we publish.
This article is part of the Open Organization Workbook project.