The future of tech comm is developer doc

by Tom Johnson on Jun 3, 2014
categories: api-doc

I attended an STC presentation the other week by Andrew Davis (one of the most helpful recruiters in Silicon Valley) on Ageism and Today's Technical Content Developer.

Ageism is simply bias against the capabilities of older people in the workplace, and it's pretty rampant in Silicon Valley. Most programmers are twenty somethings who live on Red Bull and free company food, who roll into at work around 10am and leave at around 7pm in the evening, only to play video games until 1am. These digital natives, who speak and breathe code, whose neuro-electrical synapses seem to be powered by the Internet, often look at someone beyond 50 as outdated, technically shallow, and too fixed in his or her antiquated ways.

There was a lively discussion during Andrew's presentation, and the topic veered into the market trends. As I have heard so often, many attendees pointed out that jobs for technical writers are drying up. Joe Malin, an API technical writer who had previously been working at Google, noted that while jobs for end user documentation are drying up, jobs in the developer documentation space, such as with APIs, are exploding.

Andrew agreed that this is the case. End users are expecting more familiar interfaces, increased usability, and general intuitiveness in applications. If end users need to consult a help file to use your mainstream application, you're probably in trouble.

But the technology behind those applications is getting increasingly complicated. More than ever there's a need for help for developers. The number of programming languages, technologies, and platforms has made the developer's world a tricky landscape to navigate.

According to John Musser, who runs the Programmable Web, poor documentation is a major obstacle in learning an API. In John's presentation 10 Reasons Developers Hate Your API, the #1 reason is as follows:

John knows APIs well. The Programmable Web maintains a directory of all the open APIs on the web, and there are more than 11,000 of them.

Is there a better fit for technical writers in Silicon Valley, regardless of age, to get both foothold and influence in tech comm than to provide solutions for the #1 problem with API documentation?

Unfortunately, many of the tech comm solutions that have been received the bulk of attention in the tech comm industry don't address API documentation with the care and attention one might hope.

Tech comm traditionally focuses on single sourcing, content-reuse, and structured authoring. This facilitates translation, supports large tech writing teams, and helps reduce time spent formatting.

Most of the APIs, however, aren't translated. They aren't delivered as printed material. And they require advanced developer knowledge to properly document. Writing code samples for 4 different languages requires familiarity with code.

Most of the API documentation sites I've seen are built on attractive and easy-to-navigate websites. For example, take a look at the documentation for Stripes, or Twilio, or Klout, or Constant Contact. (I'm planning another post that surveys around 50 or so API doc sites. )

To thrive in the API doc space, are the skills you need "structured authoring" or expertise at "single sourcing"? I don't think so. In fact, structured authoring techniques are somewhat antithetical to the needed collaborative authoring with engineers. The developer doc skills you need are a bit different:

• Knowledge of programming languages (C++, Java, Python, JavaScript, Ruby)
• Ability to publish on a front-end web platform
• Ability to collaborate with twenty-something engineers in a productive way

REST APIs actually have a structure that you can use to make the documentation interactive. Check out RAML and Swagger. I haven't explored these technologies yet, but when you consider the needs for REST APIs to demonstrate calls and responses, parameters and other options, the traditional tech comm strategies using things like DITA don't provide the needed structure in any special way. Beyond a table, there's nothing in the concept, task, or reference spec that addresses the needs of API documentation.

Granted, there's a lot in basic technical communication that does go a long way in creating developer documentation. Learning how to communicate complexity is our speciality, and when you use visual communication, copious examples, readable formatting (lists, subheadings, small paragraphs), clear sentences, defined terminology, progressive disclosure, sample exercises, demo pages, and more, you're doing the bulk of the work of communication already.

Yet it seems more than communication skills are needed to thrive. You'll always be at a disadvantage to those who speak code fluently. Those 20 years of writing experience mean nothing if you can't quickly articulate what a class or function does.

I see the developer doc space as one of the great opportunities before us, and one that the tech comm community can tackle. Imagine if technical writers could provide solutions for making API documentation much more usable? Imagine if we could leverage established techniques of our trade for getting people up and running quickly with developer tasks? Imagine if we had modern front-end platforms that made it easy to consume API and other developer information? Imagine if we had ways to collaborate with non-writers on content and still publish complex deliverables?

API documentation is a topic I'll be exploring on my blog for a while.