Blog Archives

Webinar on API technical writing with STC India

Are you interested in learning about APIs and API technical writing? Join us for a webinar, hosted by STC India. I’ll demo a couple of APIs and discuss the role of a technical writer in this area of the software industry. We’ll look at examples of API documentation, and discuss what type of documents an app developer expects when using an API.

The title of the webinar is “Introduction to API Technical Writing”. It’s intended for technical writers who know little about APIs (application programming interfaces) and want to explore the field of API technical writing. My hope is that, after attending this webinar, you’ll have the knowledge and tools you need to head off on your own explorations.

APIs (application programming interfaces) make it possible for applications to share information with each other. You could say that APIs are the communication channel of the online world. Developers need help hooking their application up to someone else’s APIs. We, as technical writers, give them that help.

Recording of the webinar [Update on 10 April 2016]: The recording of the webinar is now available on YouTube: Introduction to API Technical Writing.

Registration details: Sign up for the webinar, and read more about it on the STC India site.

Date and time: Friday 18 March 2016, at 1pm Indian time – that’s 6.30pm in Sydney. The session lasts one hour.

Who can join? Anyone. It’s free of charge, and you don’t need to be a member of the STC.

Topic overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer.
  • Our audience – the developers who need our documentation to use APIs in their applications.
  • The types of API we might be asked to document.
  • Demos of 2 APIs that you can play with yourself.
  • What API documentation consists of.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.

Hope to “see” you at the webinar. 🙂

API Technical Writing – tcworld India 2016

This week I attended tcworld India 2016 in Bangalore. What an amazing experience! I’ll write a summary of the conference soon. First, here are some notes on a session that I presented at the conference: “Introduction to API Technical Writing”.

The slides for my presentation are available on SlideShare: Introduction to API Technical Writing (slides).

Presentation overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer, and of our audience – the developers who need our documentation to use
  • APIs in their applications.
  • A technical writer’s view of the types of API we might document.
  • Demos of 2 APIs that you can play with yourself.
  • The components of API documentation.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.
  • Why API technical writing is a good field to be in.

API Technical WritingThank you so much to everyone who attended the talk. The room was packed to overflowing. After the session, and indeed throughout the conference, people came up to discuss the field of API technical writing and to show me things they were working on. A number of conference attendees do API documentation as part of their role, and it was very interesting to see the variety of requirements even in this niche within a niche: API documentation within the technical writing profession.

For the next tworld India, I think it’d be a good idea to have a panel discussion on API documentation. We could invite 3 or 4 people working on different types of APIs, and within different environments (such as internal versus external documentation, or integrations).

How a developer accesses an API

This post is one in my emerging series of API basics from a technical writer’s point of view. How does a developer get hold of an API, so that she can use it in her application?

The other day, I was chatting to folks in our Marketing team about the three essential items of information an API quick-start guide should give developers:

  • Where to download the API and other tools you need.
  • Where to get your API key or other required app credentials.
  • A hello world app or some basic sample code.

During that discussion, I realised that the first item (“download the API”) differs depending on the type of API you’re discussing. It’s not always a case of downloading the API and adding it to your development project. Sometimes you don’t need to download anything – you just send a request. Sometimes the download happens each time your application needs to use the API. And sometimes you download something in your development environment and compile it into your application project.

Before the recent discussion, I’d understood the difference subconsciously, but during the conversation it became clear to me that this is something worth bringing to the fore, especially for those of us who need to document or market APIs. It’s a useful way of becoming more familiar with the types of API that we’re writing about. (If you’d like to know more about the various types of API, take a look at my attempt at a tech writer’s classification of APIs.)

Calling a REST API or other web service API

As a developer using a REST API or other web service API, you don’t necessarily need to download anything. You can simply start sending requests over HTTP and receiving responses from the API, which does all the work on the server (“server side”). In some cases, however, the API developer or the development community supplies client libraries that developers can download to provide the basis for their app’s interactions with the API. Examples are the Flickr client library for .NET, the Twilio client libraries, and the client libraries for the Google Maps web services.

Importing a library-based API

For a library-based API, you need to import a library of code or binary functions into your development project (your application). Then you can use the functions and objects in your code. When using a JavaScript API, for example, you get the API by including a <script> element in your HTML page. The <script> element loads the library supplied by the API. In this case, the download of the API happens every time the browser loads the HTML page. This type of API is sometimes referred to as “client side”, because it runs in the browser on the user’s computer. To see an example, take a look at the documentation for the Google Maps JavaScript API, which describes the <script> element needed to load the API library.

For an Android API, you install the Android SDK and then add any additional SDK packages into your development project, within your IDE. (An IDE is an integrated development environment, such as Eclipse or IntelliJ IDEA.) In this case, the API download happens when the developer builds their application. See the Android documentation on installing the SDK and additional packages. The Google Maps Android API, for example, is one of a number of APIs distributed via the Google Play Services SDK, which is one of the packages described in the above link.

Downloading a flower

Recently encountered in my neighbourhood: This sulphur-crested cockatoo is importing a flower recently downloaded from a bottlebrush tree. 🙂

How a developer accesses an API

What is an API client library?

Client libraries are sometimes called helper libraries. What are they and how do they help developers use an API?

Over the past year I’ve run a few workshops on API Technical Writing. Part of the workshop content is about client libraries, and I decided it’s worth discussing this topic in a blog post too. It’s of interest to technical writers who are documenting APIs, particularly web services and REST APIs.

What is a client library?

A client library, sometimes called a helper library, is a set of code that application developers can add to their development projects. It provides chunks of code that do the basic things an application needs to do in order to interact with the API. For example, a client library may:

  • Provide boiler-plate code needed to create an HTTP request and to process the HTTP response from the API.
  • Include classes that correspond with the elements or data types that the API expects. For example, a Java client library can return native Java objects in the response from the API.
  • Handle user authentication and authorisation.

How is that useful?

Looking at the developer who’s using the API: With a REST API or any web service API, the developer could be using any of a number of programming languages to make the API calls.

Wouldn’t it be great if we could give them some code in their own language, to help them get started with the API? That’s what a client library does. It helps to reduce the amount of code the application developers have to write, and ensures they’re using the API in the best supported manner.

Examples of client libraries

In some cases, the API developers provide client libraries for the API. In other cases, client libraries are developed and supported by the community rather than the API developer.

For example, here are the Flickr API client libraries listed by programming language, all maintained by the developer community:

Here are more examples of client libraries, listed per API:

Is a client library the same thing as an API?

No, although they’re closely related. My post on API types describes library-based APIs, which are libraries of code that developers need to import before they can use the API. So, how does that differ from a client library?

Here’s how I see the difference between library-based APIs and client libraries:

  • Library-based APIs are those where the developer needs to import or reference a library of code or binary functions before the application can interact with the API. For example, the documentation for the Google Maps JavaScript API describes the HTML <script> element needed to load the API library.
  • Client libraries are additional libraries of code that are provided to make a developer’s life easier and to ensure applications follow best practices when using the API. In general, you can call the API directly without using the client library. (In some cases, though, the client libraries may be the preferred or even the only supported means of interacting with a particular service.)

I’d love to hear your thoughts on this topic – does the above summary make sense, is it useful, and what have I left out?

Introduction to API tech writing – upcoming webinar

On Wednesday February 11th, US EST (that’s Thursday here in Australia), I’m presenting a webinar about API technical writing. It’s the first in a series on API technical writing from the Society for Technical Communication. I’d love it if you could join me online.

The role of API technical writer is exciting, rewarding, and challenging. I’ve been working as a full-time API writer for 18 months now, and I love it!

APIs are a hot topic in our field, and technical writers with the skills to document them are in high demand. Many technical writers are keen to know more about the role, but it can be hard to find information. Sometimes there’s so much information that it’s difficult to know where to start. In presenting this webinar, my aim is to give you a good idea of the role of API technical writer, and some excellent starting points to explore the world of APIs.

Details of the webinar

Title: Introduction to API Technical Writing.
Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am on Thursday here in Sydney!
Duration: One hour.
Fees and registration/signup: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.

The session covers the following topics:

  • What an API is and does.
  • Introduction to the role of API technical writer and our audience.
  • Overview of the types of developer products we may be asked to document – APIs and others.
  • Types of APIs, including REST APIs, other web services, library-based APIs like JavaScript, and more.
  • A couple of live demos of APIs that you can play with at home: a JavaScript API and a REST API.
  • Examples of good API documentation.
  • The components of API documentation, and the technical writer’s role in the creation of each component.
  • A day in the life of an API technical writer.
  • Tips on getting started in the role.

Here’s a link to the slides on SlideShare: API Technical Writing.

Introduction to API technical writing

More in the STC’s webinar series on API technical writing

Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.

I hope to “see” you at the webinar!

%d bloggers like this: