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!