API technical writing (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Yesterday it was my turn to present a session.

My presentation was titled, “API Technical Writing: What, Why and How“. (The link is to the slides on SlideShare.) My aim was to introduce technical writers to APIs (Application Programming Interfaces) and to the world of API documentation. I hoped it would be useful to writers who’ve had very little exposure to APIs, as well as to those who’ve played with APIs a bit and want to learn about the life of an API technical writer.

Overview

Here’s a summary of the presentation:

  • Introduction to the role of API technical writer.
  • Overview of the types of developer products we may be asked to document, including APIs (application programming interfaces), SDKs (software development kits), and other developer frameworks.
  • What an API is and who uses them.
  • Examples of APIs that are easy to play with: Flickr, Google Maps JavaScript API
  • Types of API (including Web APIs like REST or SOAP, and library-based APIs like JavaScript or Java classes).
  • A day in the life of an API technical writer—what we do, in detail.
  • Examples of good and popular API documentation.
  • The components of API documentation.
  • Useful tools.
  • How to become an API tech writer—tips on getting started.

Demo of the Flickr API

I did a live demo of the Flickr API. It worked! The demo gremlins hadn’t found me yet.🙂 If you’d like to play with this API yourself, take a look at the Flickr Developer Guide (and later the Flickr API reference documentation). You’ll need a Flickr API key, which is quick and easy to get. Slide 23 in my presentation shows the URL for a simple request to the Flickr API.

Demo of the Google Maps JavaScript API

My second demo showed an interactive Google map, embedded into a web page with just a few lines of HTML, CSS and JavaScript. I used the Google Maps JavaScript API. If you’d like to try it yourself, you’re welcome to start by copying my code. It’s on Bitbucket: HelloMaps.HTML. This code is what you’ll find on slide 28 in my presentation.

Feeling adventurous? Grab another set of code, which adds a weather and cloud layer to the map: HelloMapsWeather.HTML.

More links

There are more links to follow in the presentation itself: API Technical Writing: What, Why and How. I hope you enjoy playing with some APIs and learning about the life of an API technical writer!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 21 May 2014, in APIs, STC, technical writing and tagged , , , , . Bookmark the permalink. 3 Comments.

  1. Thanks for this and all your write-ups of the Summit, Sarah! Just as you pointed out on my blog, it’s very interesting to read another’s perspective on presentations I have seen and, sometimes, written about. It was a pleasure hanging out with you, and I hope our paths cross again soon! Enjoy your travels through the beautiful American Southwest.

  2. You’re presentation was one of my favorites at summit 2014, it was just in depth enough for pretty novice API-ers (like me) to get a grasp of the wild world APIs. I especially liked the calling demo, since that was probably the first thing I learned when I started working with APIs and it’s really what made the concept click for me, I can imagine it did the same for other attendees.

    I’m currently a tech writer at a web hosting company so I’ve been able to get my feet wet with APIs, and was even given the freedom to restructure parts of my company’s SDK. I’m very interested in applying for a job as an API tech writer but still feel under-qualified. When you started applying for API documenting positions, did you do anything specific to show off your API documenting skills, like a portfolio website or sample docs attached to an application? How did you transition from a software tech writer to an API tech writer? I feel like I’ve just begun to straddle the gap between tech writer and API tech writer, so I’d appreciate any advice you’re willing to give. Thanks, hope you made it home safe from AZ.

    • Hallo Meagan

      Thanks! I’m so glad you enjoyed the presentation.

      When applying for the role of API tech writer, I had some documentation samples to show and also some simple code that I’d written. I was lucky, in that the docs I had written were publicly available on the web, so I could just link to them. I put my code samples on Bitbucket, and linked to those as well.

      When I started working as a tech writer, I worked on user-focused docs as opposed to developer-focused docs. While working at Atlassian, I documented products that were intended for use by developers (although not at first the APIs) and got to know the developer community that way. Then I started finding the APIs interesting, along with other development frameworks. So I played with those, and moved into documenting them too. I was lucky, in that I had some very good guidance from a few engineers who knew exactly how they liked their documentation.

      I’m not sure how much you’ve managed to work with code yet. I’d advise choosing a language like Python to start with. It’s a versatile language, in that you can use it for basic and really useful scripting (e.g. to read in a file, do some data crunching, and write out results) and you can also get more complex, including object orientation. Python is well respected in the development community, which is always a good thing. Here’s a recommended course for getting started with Python:
      https://developers.google.com/edu/python/?csw=1

      It’s good to be able to hack away in HTML, CSS and JavaScript. For CSS, it’s enough to know the basics. In most organisations, the UX designers are the CSS wizards and other people know enough to read the stuff and add some basic styling. A reasonably good knowledge of JavaScript is a very good thing.

      I hope this helps.

      Cheers
      Sarah

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: