Follow-up on yesterday’s talk about API technical writing

Yesterday I was privileged and delighted to speak at a meeting of the STC Silicon Valley Chapter in Santa Clara. Thanks so much to Tom Johnson and David Hovey for organising the meeting, and thank you too to all the attendees. It was a lovely experience, with a warm, enthusiastic and inspiring audience. This post includes some links for people who’d like to continue playing with the APIs we saw last night and delving deeper into the world of API documentation.

The presentation is on SlideShare: API Technical Writing: What, Why and How. (Note that last night’s presentation didn’t include slide 51.) The slides include a number of links to further information.

The presentation is a technical writer’s introduction to APIs (Application Programming Interfaces) and to the world of API documentation. I hope it’s 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

During the session, I did a live demo of the Flickr API. 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, follow the getting started guide in Google’s documentation. You’re welcome to start by copying my code. It’s on Bitbucket: HelloMaps.HTML. That code is what you’ll find on slide 28 in the presentation.

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 26 August 2014, in APIs, STC, technical writing and tagged , , , , , . Bookmark the permalink. 4 Comments.

  1. Hi Sarah, do you have any advice for keeping your API documentation up to date? Generating the documentation from code comments doesn’t always solve that problem, as a dev might make a drastic code change and not update the code comments that are used in the generated docs.
    I’m curious as to how you guys keep this tutorial (https://developers.google.com/maps/documentation/javascript/tutorial) up to date with each release? Does somebody test it with each new version of the API? Do you have automated tests backing the sample code used in the tutorial?
    We have an API under continuous development so there are drastic changes in the api between versions and the documentation can quickly fall out of date.

    • Hallo Tony

      That’s a very good question. Coincidentally, it’s the topic of a talk I’ll be giving at Web Directions South next month.

      The code on that particular page (the one you linked to) is very simple, using only the core parts of the API, so we maintain it manually – we keep an eye on the API and update the doc if necessary. But we have a large number of samples in this section of the docs which are indeed hooked up to automated tests.

      Cheers
      Sarah

      • What kind of automated tests are you using to maintain the code? Are you using any technology to cite the sample code? Or are you manually copying an pasting the JavaScript/HTML into your documents?
        Sorry for so many questions.

      • We use internal tools. In most cases we’re able to auto-extract sample code from the repository and display it in the document on the fly. Setting up automated testing and a continuous build environment is not trivial. The best thing is to use the same tools as the engineers do, and to get their help in setting up the environment.

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: