Uber’s 3-Step Approach to Getting More Engineers to Document

Documentation isn’t always a top priority for engineers. That’s a challenge nearly every company experiences, including Uber.

“There are always so many other things on engineers’ plates,” says Stephanie Blotner, Technical Writer at Uber. “How do you make documentation a priority?”

Uber has engaged with this challenge using three methods: cultivating motivation, providing education, and reducing tooling friction.

Cultivating Motivation

Documentation gets written when employees are motivated to write. Uber achieves this in a few different ways.

First, documenting code is a part of software engineers’ competencies, which are used for performance evaluations.

“We're saying documentation is important. Not only for your team, but for your career.”

Company leaders also share messaging around the importance of documentation in emails, all-hands meetings, and other communication.

Proactively, you’ll hear managers tell an engineer: we think it’s important you document what you build to help other engineers. Reactively, leaders recognize and celebrate teams that document effectively. They then set these teams’ approach as the company standard.

Blotner and her team motivate engineers by showing them how documentation can alleviate specific pain points. For example, if she identifies that one engineering team constantly answers questions from other teams, Blotner shows exactly how documentation can solve that problem.

“We want to make it clear that we’re not documenting things just for show,” she says. “We’re doing it to solve a specific problem.”

Blotner and her team could go to each department and encourage engineers to document. But it’s far more effective to have someone from within a team lead by example.

She and her team identify managers and employees passionate about documentation and encourage them to serve as stewards of writing. She then sends a newsletter to teams where she identifies Doc Stars—colleagues who create and update quality documentation.

Teammates have told her how exciting it was to be publicly recognized. She’s seen how it encourages them to continue their best practices.

She’s also seen the number of Doc Stars increase, indicating that this public recognition is inspiring others to document.

Providing Education

Being motivated to write isn’t the same as documenting effectively. At Uber, educating engineers on how to document starts from day one.

All new engineers and engineering managers attend a technical communication course during their onboarding. This course, taught by either a tech writer or fellow engineer, helps new team members know the importance of documentation, when to document, and how to break down ideas for easier consumption.

The onboarding course is about an hour in length, so it only touches the surface of good writing. To compensate, Blotner's team also offers an optional monthly tech writing course.

This course dives deep into how to write effective documentation by focusing on common writing bugs and how to address them.

Two common writing bugs Blotner's seen over the years are:

• Lack of empathy—Engineers may not fully consider their audience when writing, which can lead them to confuse the reader with either too little, or too much, context.
• Grammar—Many people default to the passive voice, but technical documentation is more actionable when written in the active voice.

While grammar is a concrete concept, empathy is not. That can make it harder to teach others. But at Uber, they’ve made this experience as concrete as possible. They’ve created a checklist of questions engineers can ask themselves to ensure they keep their audience's needs in mind.

Questions like "who is the audience," "what is their workflow," and "what are their pain points" keep the audience top-of-mind. Overall, Blotner hasn’t found too many engineers who struggle with understanding why empathy is important. “I think [that's] because they’ve experienced it themselves,” she says. “They’ve been on the receiving end [of poor documentation].”

Reducing Tooling Friction

Building a writing culture means reducing any friction involved in the process. Education helps—the more confident the writer, the more willing they are to write.

“We don’t need to add more friction to writing. There’s enough friction there, already.” 

But friction also occurs within the tools you use, particularly when teams have preferences for where they document. This can create fractured knowledge and writing experiences.

Blotner admits that siloed information is an issue at Uber. The good news is that engineers have contributed a lot of content. But it lives in many different places, making it hard to navigate. That can lead to duplicate and stale information.

“That can reduce the motivation to write,” she says. “Because you may think, ‘Oh if I write this, and no one can find it, what’s the point?’”

To address this, Uber’s Technical Writing team takes a two-pronged approach:

1. When writing: Her team meets people where they prefer to be. If an engineer wants to draft or collaborate in a certain tool, so be it.
2. When publishing: When the content is ready for public consumption, it’s moved to a consistent location (either by publishing directly to that location, or embedding it).

A Writing Culture Like Uber's Takes Effort

Uber has made conscious efforts to nurture their internal writing culture. They’ve realized that good documentation doesn’t come through a mandate. People need to be motivated to exert this additional effort in their day. Seeing how documentation can improve their lives gives them this motivation.

The courses and workshops dedicated to tech writing don't just educate employees—they demonstrate how much importance the Engineering organization places on good writing.

And thinking of ways to reduce friction—across the entire writing experience—ensures that the writing culture Uber has built will remain, regardless of changes along the way.

This post describes Stephanie’s personal opinions and does not necessarily reflect the views of Uber.