“Wait a minute — there are more than 200 writers on your team who can explain all this technology to others? How come we didn’t know about this!?”
It was a fair question asked by one of my Salesforce coworkers. He and his team were tasked with writing content about a new feature, and he didn’t know that a Content & Communications Experience (CCX) team existed that could help. He’d heard about technical writers. But he didn’t know what people with my job title do, or why companies hire teams of people with my skill set. It wasn’t his fault.
Historically, technical writers work in the shadows of software development teams. We write content that most people try to avoid unless they’re in a jam — online help, release notes, implementation guides, API developer guides, and more. We’re like embedded journalists, who, from the start of the product design process through the end of the coding cycle, ask tough questions about feature behavior and suggest ways to solve problems with content. We create UI text, graphics, videos, popups, walkthroughs, interactive tutorials, and more on-screen mechanisms that provide clarity or instruction. Ultimately, we try to write the most concise content possible. (Because who has time to read all that stuff?) We work with designers, product managers, and engineers to build intuitive features that require less explanation and help customers do their jobs.
- They can help you understand complex subjects in an easy-to-understand way. While developing content for various technologies, tech writers interview the experts — teams of engineers. Usually, engineers are so smart and detail oriented that their answers seem long-winded or difficult to comprehend. Tech writers streamline the information. To write the best, most succinct content possible, tech writers pull apart and digest what they learn from engineers, becoming technology experts themselves. The result is that in their efforts to create clear content, they can explain the most complicated subjects like the best teachers you had in school. You can learn about technology from tech writers because they’ve done all the studying for you.
- Tech writers can provide you with useful content that you didn’t know existed. Before tech writers begin the content creation process, they usually gather every internal planning document related to the feature they’re assigned to chronicle. Specifications, code samples, test or business cases — tech writers have explored them all. Tech writers also help define or locate best practices, gotchas, prerequisites, or user stories that clarify the most intricate (or irrelevant) details about a new product or technology. Plus, once the feature is made available to customers, tech writers track down customer feedback and help resolve issues where possible. Typically, tech writers have a 360-degree view of a technology they’re working on, and they can send you content you’re scrambling to find or didn’t know was available.
- They have relationships with other people who can help you. Even if a tech writer can’t answer your questions, they know someone who can. Similarly to how films are considered a collaborative art, so is technology. Many people and teams work together behind the scenes to create a feature, and a tech writer builds relationships with all of them to track down the information they need to write content. Often the writer is the glue between teams, helping them understand limitations or communication gaps simply because their job requires them to collect insights across specialized roles. Whether it’s product marketing, customer support, product management, user experience (UX), product management, or developers, tech writers collaborate with them all, so they can put you in contact with the right person.
- Tech writers can give you a reality check. When a new feature or technology is built, rumors abound as to what problems it solves. Luckily, a tech writer is a source of truth. The goal and craft of technical writing is to convey accuracy — above all else. Unlike other forms of writing used to stir emotion or grab your attention, tech writing’s purpose is to communicate facts. Tech writers are walking encyclopedias. They can tell you exactly why something was built and how it really works.
Facts aren’t always fun and that’s led technical writing to have a dry reputation. But tech writers are a lively bunch of characters. At Salesforce, we have writers who sew costumes for theatre, tour the world playing Balkan or bluegrass music, publish mystery novels and avant-garde poetry, run 100-mile ultramarathons, and swim in between the Greek Isles for kicks. As one coworker recently told me, “Your team is so cool and saves us so much time…why didn’t we know about you earlier?”
Originally posted by Gavin Austin for Salesforce Engineering on Medium