Tap, tap…is this on?

I’m back at the blog, after a year, five months, and a couple of days. As my first blog post in a while, please be patient. It might be a bit rough.

How time flies. To catch up…

I’ve been working as technical writer since last January. Although I enjoyed working as an academic, it became clear that academia and I weren’t really cut out for each other. So, I’m back in the Pacific Northwest writing technical documentation for Amazon Web Services.

Returning to industry

It was almost as if I’d never left. I have to credit the amazing group of people I work with for making the transition a smooth one. Working in big tech is pretty much as I recall: lots to do, little time to do it—so, maybe not that different from academia.

While Amazon, in general, is famous for its short average tenure, on our team, the low average tenure is simply because we’ve been hiring new writers and we’re looking for more. We’ve got a lot of work to do! Good people, interesting work, decent pay…can’t complain, and did I mention that we’re hiring?

I’m finding the work interesting in all the dimensions that intrigue me: Technical novelty, information design, and collaboration with engineering.

The part of the product I work on has been around for a while and is still growing, so addressing the information needs of both new and experienced users presents some interesting challenges–made even more interesting by the short schedules. The collaborative group of engineers, designers, and writers I work with, however, make tackling these challenges both enjoyable and possible.

What’s new in the scholarly literature?

While catching up, I thought I’d see what’s new in the API documentation research. A quick (and by no means comprehensive) survey of the academic work that’s been published on API documentation since the list of New articles on API documentation I posted three years ago shows that software developers:

  • Still want better docs with more code samples.
  • Are still trying to create them with automation (instead of tech writers)
  • Are still not citing work from actual technical communication research.
  • Still don’t seem to do much research past surveys.

Sigh. Everything old, is new again.

I’ll organize this more later (and hopefully change some of these initial impressions for the better). In the meantime, I’m waiting for the research that explores Why is this still the case after over a decade of research pointing out the issues (repeatedly)? This 2018 paper by Murphy et al. is in the right direction by exploring some of the challenges that practitioners face trying to design usable APIs–a prerequisite for making it easier to create usable API documentation. Maybe there’s a research opportunity for a similar study with technical writers.

Nevertheless, it’s good to see all the research being published on API documentation. It’s much better than the comparative handful of articles that were available on the topic when I started researching it in 2008.

Murphy, L., Kery, M. B., Alliyu, O., Macvean, A., & Myers, B. A. (2018, October). API designers in the field: Design practices and challenges for creating usable APIs. In 2018 ieee symposium on visual languages and human-centric computing (vl/hcc) (pp. 249-258). IEEE.

Leave a Reply