We recently convened a panel of some of the most thoughtful technical writers working for some of the most important companies in the industry, asking them a host of questions about how they encourage documentation and build consensus. Here are some illuminating takeaways:
Technical writers have flexibility when it comes to their positioning in an org chart
There are generally two main approaches to organizing technical writers: they can exist as a centralized entity that supervises documentation across an organization, or embed themselves with specific teams, paying closer attention to one aspect of the work being done.
“We’ve tried both models and I think there’s pros and cons to both,” said Deepa Jacob from LinkedIn. “I think the embedded model has a few advantages and works better for certain scenarios. For example, being embedded in a team means we can make a meaningful impact on a high‑impact project. Maybe that’s a team with a new tool or technology that needs a suite of docs quickly… I think the pros of this is that you gain speed through proximity and access to the developers. That said, it’s very hard to scale this at a company of our size. So, as a centralized team, we can ensure that there is a consistent unified experience across the company, and we can standardize procedures, templates and style guides.”
Stephanie Blotner from Uber sees a clear upside for centralizing writers so that they can maintain focus on the most important projects.
“One of the benefits I’ve seen from the centralized model is that you find writers being pulled less into projects that might not have as big of an impact,” said Stephanie. “For example, if a writer is embedded with a team, they might feel obliged to work on projects like newsletters or small updates that don’t have a big impact. Whereas when you have a centralized team, you can use your knowledge about the problem space and the business objectives to make sure that you’re focusing on the top… projects that are going to help the largest number of people.”
Spotify describes how they use education to scale out their impact. “We just started a technical writing course at Spotify,” says Kate Dolan, “where the technical writers are each teaching different subjects that we think help describe the different types of documentation. This is so that engineers can learn how to write their own documents.
We don’t want to replace ourselves, but we’re trying to give tools that engineers can use so that they feel more empowered to take a first stab at a document, and then have us come in, sharpen it and take it from there.
As a company matures, documents maintenance/ownership requires regular attention, creativity, and automation
Jatin Billimoria of Splunk sees his job as analogous to a gardener, he says.
It’s a continual process of care and feeding. It’s like a garden in that you have to add fertilizer. You have to make sure that specific portions of the garden are well taken care of, and people need to come in and plant seeds or take out the weeds.
Additionally, technical writers at mature organizations can provide certain cues to let engineers know that particular documents have the most up to date and complete information
“At LinkedIn, we’ve been trying to identify the source of truth, so to speak, and call those documents ‘certified’”, says Deepa Jacob. “So a few quarters ago we introduced this concept of certified pages, which means that it is officially endorsed by our team. It’s published to the widest audience possible, and it’s considered to be the most trustworthy source of content.”
We promote the certified pages in our internal search which helps with discoverability and the confidence that the content is accurate.
In an attempt to make this process more efficient, LinkedIn is experimenting with a process by which they might automate the certification of the best pages.
“One project that we have going on currently is trying to score these end user facing pages. We’ve defined a scoring rubric, and we are hoping to automate this so that it can provide this document quality insight for managers and content owners. It will be surfaced up in the dashboard. If you’re able to automate it, you can reduce the time and resources it takes.”
Standardization is your friend and ally
Getting engineers across the company to document their work in a uniform manner is a huge bonus, and falls within the purview of a technical writer.
“At Spotify, we have what’s called the Spotify technical writing handbook,” says Kate Dolan. It was modeled after the Spotify engineering handbook so that it could feel more familiar to the engineers when they’re writing their documentation. It’s very in‑depth; it goes over things like when to use bold and how to write a golden path. It’s a big document, but it’s well laid out… It’s in almost every Slack channel, and we constantly ask, ‘Is this helpful? Did you learn anything?’
Writing the handbook was a great practice for us to establish writing standards at Spotify and then circulate that information with the engineers and anyone else who’s writing technical documentation.
Technical writers need to strategize how they encourage updates
Documentation will go stale quickly if maintaining documentation isn’t part of the development lifecycle, says Stephanie Blotner.
You have to treat it like an engineering problem. This means, for documentation bugs and maintenance, it can help to “use the ticketing systems that engineers use to track and fix bugs in code… so that documentation can be triaged and prioritized.
Designing quality metrics is crucial
Sifting through the documentation created by engineers can be challenging if a writer doesn’t know what, exactly, is valuable and how it would be of assistance. Writers can and should set metrics by which they gauge the quality of the content they oversee.
“The discoverability of content and finding fresh content causes a lot of friction for developers,” says Deepa Jacob.
You want to empower them to produce and publish the software with the least amount of friction. And so the metrics that we’re calculating in terms of content is what, what those would be.
We ask, ‘Is it easily described? Is it discoverable just in the first 10 search results? When was it last updated?”
Another approach is to engage with engineers to solicit feedback on what they find useful, using the results to define your metrics.
“We recently conducted a survey for our internal engineering teams specifically asking about different aspects of documentation,” says Jatin Billimoria. “We asked things like, ‘Are you able to find information easily? Can you search for it easily? Is the documentation you’re reading easy to understand? Is it up to date? The clear issue that stood out was that our content was hard to find and not up to date. Also, it turned out that very few people had backups for the content that they maintain. So if they left the company or transitioned to another team and decided, ‘Hey, I’m done with this document,” there was no backup owner. This is an early indicator for future stale content.
What does success look like?
Documentation will never be a “favorite” activity of engineers; still, it serves an important function that contributes to engineering excellence and a company’s success.
You have to be ambitious but realistic. I don’t think there’s going to be a world where in a large company, all engineers say, ‘I love writing documentation!’ and ‘It’s perfectly easy to find everything!’
But, “if there are specific business metrics or goals that you’re driving around developer productivity, or are trying to get adoption of X technology, you can use those metrics or adoption rates as indicators that your knowledge sharing tools and systems were successful,” says Stephanie Blotner.
At mature, high-functioning companies, technical writers can often function like a building’s foundation; their function isn’t visible to the outside eye, and yet they’re critical to the structural integrity of the endeavor. Here at PlusPlus, we’re at work developing the tools that will make this labor easier and more effective, enabling teams to better communicate, operate more efficiently, and execute their very best work.
