The Role of the Editor in Technical Documentation With Mike Pope, Technical Editor at Google
Last updated on Mar 14, 2022
Mike Pope, Technical Editor at Google, joined us in this episode of Knowledgebase Ninja Podcast to share his three-decade-long technical documentation journey, his transition from a technical writer to a technical editor rising demand and the need for dedicated technical editors for the documentation industry. Check out all the other episodes here.
- Mike Pope’s LinkedIn
- Mike is creating technical documents since the 1980s
- Mike worked for Microsoft for seventeen years
- Mike transitioned from technical writing to editing fifteen years ago
- Mike spent the initial seven years of his career without an editor
- Google host a International Writers Conference
- Mike works in Google’s Cloud Division as a technical editor
- Mike was working in support and training when a documentation opportunity came up. The opportunity seemed interesting so Mike went for it and started his journey with a small Seattle database company. Soon after Mike started working with some of the best companies in the industry such as Asymetrix, Microsoft, AWS (where he worked on security docs), tableau, and Google
- At Microsoft Mike worked in the development division, this was when Mike transitioned from a writer to a full-time editor
- Google cloud division concentrates its efforts on enterprise solutions, as a result documentation primarily focuses on developers and engineers. Google keeps the tools integrated to bring all stakeholders together, especially writers and developers. Writers compose, stage the document, get the document approved, and release it into a huge depot that collects all the documents in one place
- AWS cloud offers many different services, where the writers’ work is differentiated based on the users and targeted audiences. Although, the ultimate mechanics of producing quality documentation remain constant
- At Google, there are centralised tools to manage workflow, but every group can publish independently. They can pick up a document, create or edit it, get it approved, and place it into the depot for publication. This is how multiple publications happen simultaneously
- Mike says that technical writers don’t have the luxury to work with dedicated editors. With editing, you have a clear set of responsibilities
- At Google, editing is teamwork that helps writers express their ideas. Apart from key writing details to follow, there is an aspect of documentation succession and objectives. Is the problem stated clearly? And is the targeted audience identified from the beginning?
- There is a “fail fast concept” in technical writing and editing, which means that the reader should know within the first paragraph if a document answers the problem they are searching for. The key target of writers should be to minimise the time the reader spends on the document
- To improve documentation, there is a classification of conceptual content models, tutorials, references, documentation, etc. so the reader knows where to find specific information
- Technical writers should have a style guide, which is also known as the police of documentation. It contains several pre-made decisions, based on research, that outline what terms to use and what terms not to use
- Using inclusive language is a key factor in technical writing. There are some standard terms in the industry that are objectionable for certain reasons. For example, the terms whitelist and blacklist – create a dichotomy that is uncomfortable for people. Therefore, it has been replaced with “allowlist and blocklist”
- The editors help writers improve as the editing process is educational and spreads a culture of quality writing throughout the organisation
- Important factors to consider when creating documentation is: what problem is the documentation trying to solve? And who are you talking to/who is consuming your documentation?
- There are multiple ways to know if your documentation is working: metrics, consumer feedback through support channels, bug reports, and direct customer feedback
- Content written with consistent vocabulary and short sentences will no doubt encourage engagement. As it is not only useful for targeted audiences but also the people not familiar with the technical language
- The documentation at Google is thoroughly instrumented for internal analytics. The information is available in centralised analytic sites (which are similar to external analytic sites on Google)
- Analytics help decide the fate of icebox documentation. These are documents that have not been updated and kept in a larger database
- The majority of traffic on Google cloud documentation comes from organic search
- At the start of Mike’s career there were no editors, just peer reviewers. His first experience of working alongside trained editors opened his eyes. He understood the need for a professional who understands technical writing and its goals
- Google calls an Internal Writers Conference every year that brings all the tech writers from all over the company (consumer, devices, cloud, etc.). Mike is grateful for the exposure he gets there to connect with people catering to different audiences, which helps to broaden his perspective
Mike’s biggest influence
“The Joy of Cooking” is a cookbook written back in 1931 by Irma S. Rombauer. Mike acknowledges the innovative explanations, clear procedures, extended notes, warnings, and effective user illustrations of this cookbook has helped him a great deal in his technical writing career.
What documentation related advice would Mike give to her 20-year-old self?
Mike wishes his younger self knew that people don’t read the documentation but scan through it searching for a particular piece of information that solves their immediate problem; so he could’ve written a lot less but targeted.
Subscribe to Knowledgebase Ninjas