• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

Dion Almaer

Software, Development, Products

  • @dalmaer
  • LinkedIn
  • Medium
  • RSS
  • Show Search
Hide Search

Technical Writing

Tech writers are underrated

July 19, 2017 Leave a Comment

I have long seen the Bay Area (and tech industry in general) hold up the engineers, or the designers, as the heroes of Silicon Valley. There is the mythology of Steve and Steve in a garage, or Jonny Ive in a pristine design lab, creating the future.

In my own experience I have seen how important all of the roles are to making sure a product, and a company, is successful.

I highlighted project managers and QA engineers in the past, and today I want to speak about tech writers. Being back at Google I have once again gotten the opportunity to work with incredibly experienced tech writers, and I want to tell the tale of two (hypothetical ones): Robin and Pat.

First up is Pat

Great tech writing requires an immense understanding of the engineering product, as well as knowledge of the range of developers (or others!) who will be using it. The writer is the bridge between the product and the engineers knowledge who built it, and the end user developers. Pat takes the time to build the relationship with both sides and go deep with the product and its goals before getting to work. By embedding with the product team, and devrel experts, she immerses in this information, and is also able to help define the product.

By working with the product team she is able to get the insights and deep knowledge, but the understanding is that the audience is not the internal team, so the job at hand is to educate and help the external developers.

Too much documentation happens at the end of the production line “and now, can you writeup some docs?” This can be natural. You don’t want to waste time redoing docs while the product is undergoing massive iteration, but by having Pat there from the beginning gives the opportunity for the information to iterate and tweak, and then it can be deeply baked at the end. Pat is very strong when it comes to information architecture and taking massive amounts of information and prioritizing and shaping it based on what is really needed.

Many tech writing teams from various past lives felt stuck in the 1990s. Their process fit a “and now we need to write the manual” type style. Books are great, but not only are they not the way that many dev learn, but they have limitations. These days, for technical products, you can bring together a slew of tools:

  1. Being able to play with the products live can be an amazing learning tool, and we all know that most people learn best by doing
  2. Video, and various widgets (including tools, playgrounds, etc) can be embedded and composed with written content
  3. Customization for the developer (e.g. show the sample API client usage using JavaScript vs. Python).

Another huge difference is that the entry point, and path, is so much more dynamic. Many developers are ending up on your content based on a problem they are having:

  1. Ugh I can’t do X
  2. [X] <= search for answers
  3. End up in a doc, potentially very deep into the docs.

The default case isn’t “I want to go visit the home page of the documentation today!”, and Pat knows that all too well.

Next up is Robin

Robin is an empathic educator. Robin loves to code and build things, going as deep as possible on not only the product, but also the competition and ecosystem.

This gives Robin a ton of context on where to delve deep. If we aren’t consciously shaping the documentation experience, then it is easy to default to equal weight on small docs in the small. In the real world every API and method is not equal, and there are tasks that developers want to accomplish that don’t line up directly to documenting code.

As Robin looks at what the developer is trying to accomplish, and both feels individual pain and witnessing the community, a slew of solutions come up. Robin is able to drive change to the developer product/platform itself this way, is able to envision new tools or fix existing ones, and the result of the work tends to be in less verbiage yet more solutions.

When working ideally, the tech writers work hand in hand with their other devrel counter parts to drive this change. Together, they prioritize the work and how best to attack the needs of the diversity of developers that use, or may use, their products.

Doing it all with style

Context is varied throughout our tools, but consistency is important too. To that end the writers and editors have built a style guide for developer documentation. This is a living document that works as a collection of best practices and contract for how documentation can work best.

This is really important work as developers naturally bounce around through various documentation and use a variety of developer products. If we can do a better job here, a developer that jumps between docs on Firebase and Android will be able to intuit a lot along that way, versus having the feeling like these words are vastly different, and having to learn the cultural norms of the docset. I am happy to see the style guide public, as we see more and more projects in open source, and the community cares more and more about documentation. If someone wants to jump in to help with TensorFlow or AMP docs, they can easily see where the writing team is coming from.

Educator

It has been really exciting to see the tech writers in our DevRel team really take on the role of educator. They care deeply about developer success, akin to the other roles. This is something that ties us all together.

We want developers to be successful, so they can build experiences that enable people in the world. This is what gets me out of bed in the morning, having the platform to help in a small way.

Developers know how important docs are, and tech writers now have a massive impact there and much beyond.

And, I want to say thank you to the tech writers who help this mission, every day.


Others in the series:

  • Project managers are underrated
  • QA engineers are underrated.

Primary Sidebar

Twitter

My Tweets

Recent Posts

  • I have scissors all over my house
  • GenAI: Lessons working with LLMs
  • Generative AI: It’s Time to Get Into First Gear
  • Developer Docs + GenAI = ❤️
  • We keep confusing efficacy for effectiveness

Follow

  • LinkedIn
  • Medium
  • RSS
  • Twitter

Tags

3d Touch 2016 Active Recall Adaptive Design Agile Amazon Echo Android Android Development Apple Application Apps Artificial Intelligence Autocorrect blog Bots Brain Calendar Career Advice Cloud Computing Coding Cognitive Bias Commerce Communication Companies Conference Consciousness Cooking Cricket Cross Platform Deadline Delivery Design Desktop Developer Advocacy Developer Experience Developer Platform Developer Productivity Developer Relations Developers Developer Tools Development Distributed Teams Documentation DX Ecosystem Education Energy Engineering Engineering Mangement Entrepreneurship Exercise Family Fitness Founders Future GenAI Gender Equality Google Google Developer Google IO Habits Health HR Integrations JavaScript Jobs Jquery Kids Stories Kotlin Language Leadership Learning Lottery Machine Learning Management Messaging Metrics Micro Learning Microservices Microsoft Mobile Mobile App Development Mobile Apps Mobile Web Moving On NPM Open Source Organization Organization Design Pair Programming Paren Parenting Path Performance Platform Platform Thinking Politics Product Design Product Development Productivity Product Management Product Metrics Programming Progress Progressive Enhancement Progressive Web App Project Management Psychology Push Notifications pwa QA Rails React Reactive Remix Remote Working Resilience Ruby on Rails Screentime Self Improvement Service Worker Sharing Economy Shipping Shopify Short Story Silicon Valley Slack Software Software Development Spaced Repetition Speaking Startup Steve Jobs Study Teaching Team Building Tech Tech Ecosystems Technical Writing Technology Tools Transportation TV Series Twitter Typescript Uber UI Unknown User Experience User Testing UX vitals Voice Walmart Web Web Components Web Development Web Extensions Web Frameworks Web Performance Web Platform WWDC Yarn

Subscribe via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Archives

  • February 2023
  • January 2023
  • September 2022
  • June 2022
  • May 2022
  • April 2022
  • March 2022
  • February 2022
  • November 2021
  • August 2021
  • July 2021
  • February 2021
  • January 2021
  • May 2020
  • April 2020
  • October 2019
  • August 2019
  • July 2019
  • June 2019
  • April 2019
  • March 2019
  • January 2019
  • October 2018
  • August 2018
  • July 2018
  • May 2018
  • February 2018
  • December 2017
  • November 2017
  • September 2017
  • August 2017
  • July 2017
  • May 2017
  • April 2017
  • March 2017
  • February 2017
  • January 2017
  • December 2016
  • November 2016
  • October 2016
  • September 2016
  • August 2016
  • July 2016
  • June 2016
  • May 2016
  • April 2016
  • March 2016
  • February 2016
  • January 2016
  • December 2015
  • November 2015
  • October 2015
  • September 2015
  • August 2015
  • July 2015
  • June 2015
  • May 2015
  • April 2015
  • March 2015
  • February 2015
  • January 2015
  • December 2014
  • November 2014
  • October 2014
  • September 2014
  • August 2014
  • July 2014
  • June 2014
  • May 2014
  • April 2014
  • March 2014
  • February 2014
  • December 2013
  • November 2013
  • October 2013
  • September 2013
  • August 2013
  • July 2013
  • June 2013
  • May 2013
  • April 2013
  • March 2013
  • February 2013
  • December 2012
  • November 2012
  • October 2012
  • September 2012
  • August 2012

Search

Subscribe

RSS feed RSS - Posts

The right thing to do, is the right thing to do.

The right thing to do, is the right thing to do.

Dion Almaer

Copyright © 2023 · Log in

 

Loading Comments...