Wednesday, September 14, 2011

Evolution of Tech Writing: Where Do We Go From Here?

In the usability studies we've done here at Google, we've found that developers are less and less inclined to read the "official" docs by default.  Rather, their first step is to do a Google search for the information they need.  Often, people turn to forums, blogs, and wikis to figure out how to do what they need to do.  

This fundamentally changes the developer support model. From the point of view of developers, it leverages the brain power of a community of developers who are all trying to accomplish similar objectives, and can learn from one another. 

For an organization offering APIs or developer tools, this enables developers to support one another, which is infinitely more scalable than trying to support all developers from in-house.

For those of us who are involved in developer support, this represents a powerful shift in how we approach our roles.  This is especially true for tech writers.

Tech writers represent the point of view of our developer community.  At the same time, we are internal to the company and have a direct connection to the teams who create the APIs. 

We can use this intermediary position to identify, and then publish, valuable information that developers would have trouble figuring out on their own.  For instance, we are uniquely able to write documentation like:
  • A developer's guide for a new API that explains what a library of calls is meant to do, and how to combine the methods in a logical way. 
  • Sample code that shows how to approach a particular task in an efficient and sanctioned way.  Bonus points if this sample can be compiled and run, so someone can copy it and use it as the starting point for their own application.
  • A reference guide that gives default values and acceptable ranges for arguments, and explains unpredictable side effects of calling a particular method.
  • Cross-product documentation that explains how to use one library in conjunction with another.
A tech writer's role is bigger than documentation.  We know what our developers are trying to accomplish, and can advocate on their behalf to make those things easier and more achievable.  We can influence the product teams on all levels, from creating a library of calls that is better architected and easier to understand, to writing APIs that use more understandable signatures.

Tech writers have a unique and irreplaceable role, and always will.   The explosion of information and support now available on the internet helps us capitalize on our unique strengths.  It frees up our time to work on the things that really matter, which makes us more valuable, and makes our jobs much more interesting.  It's a good time to be a tech writer.

No comments:

Post a Comment