This post originated from an RSS feed registered with Java Buzz
by dion.
Original Post: Tech writers are underrated
Feed Title: techno.blog(Dion)
Feed URL: http://feeds.feedburner.com/dion
Feed Description: blogging about life the universe and everything tech
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:
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
Video, and various widgets (including tools, playgrounds, etc) can be embedded and composed with written content
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:
Ugh I can’t do X
[X] <= search for answers
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, the platform to help in a small way.
And, I want to say thank you to the tech writers who help this mission, every day.
Tech writers are underrated was originally published in Ben and Dion on Medium, where people are continuing the conversation by highlighting and responding to this story.
Previous Topic
